paralleldrive/aidd-structure

Standard folder structure

types ← services ← plugins ← components
  ↑         ↑         ↑
  └─────────┴─────────┘ (types only depend on types)

Dependency rules

LayerDependency {
  layer: "components" | "plugins" | "services" | "types"
  mayDependOn: String[]
  mustNotDependOn: String[]
}

DependencyRules [
  { layer: "components", mayDependOn: ["plugins (Observe<Data>, void actions)", "types"], mustNotDependOn: ["services"] },
  { layer: "plugins", mayDependOn: ["services", "types", "other plugins"], mustNotDependOn: [] },
  { layer: "services", mayDependOn: ["other services", "types"], mustNotDependOn: ["components", "plugins"] },
  { layer: "types", mayDependOn: ["other types"], mustNotDependOn: ["everything else"] }
]

Constraints {
  Never: components → services
  Never: services → components or plugins
  Never: types → anything except types
}

components

UI components or elements (also called "elements").

From plugins: only Observe<Data> for reactive re-renders and void-returning action functions.

plugins (if using @adobe/data/ecs for state)

ECS Database.Plugin declarations. Usually depend on services, types, and other plugins.

services

Asynchronous data services, each in its own folder. Immutable data only. Adhere to namespace guidelines.

Async patterns only: Observe<Data>, Promise<Data>, AsyncGenerator<Data>, void actions.

External code depends only on interfaces, never on implementations.

types

Pure functional types and associated pure functions. Adhere to namespace guidelines.

Nested structure

When a component has implementation-specific sub-parts, mirror the root structure inside it:

components/my-component/
  components/
  plugins/
  types/

Execute

fn whenAddingOrMovingCode() {
  Constraints {
    Place code in the correct layer (components, plugins, services, types)
    Check dependencies against the dependency rules
    Fix any violations (e.g. components importing services)
  }
}