Choose a layer from the problem you are solving, not from a directory name or an old product label.
Layer map
| Layer | Owns | Does not own | Developer entry |
|---|---|---|---|
| AFS | Paths, mounts, provider operations, capability declarations | Site themes, AUP primitives, Blocklet release policy | AFS |
| AFS UI | How UI devices relate to AFS (architecture explanation) | A portable third-party device SDK promised as product | AFS UI (this board) |
| AUP | Semantic UI tree, events, bindings, sessions, degradation rules | Website content model, package lifecycle | AUP |
| Web Device | Static site trees, pages, content objects, components, HTML render | Interactive session protocol, identity lifecycle | Web Device |
| Blocklet | Package vs instance, local run, manifest/check, composition boundary | Core AFS op semantics, AUP node catalogue | Blocklets |
| Identity & data spaces | Caller context, DID-scoped storage, session data views, membership surfaces | AFS provider authoring, site markdown pipeline | Identity & Data Spaces |
| ARC CLI / runtime | Host process, service lifecycle, operational commands | Replacing the contracts of the layers above | ARC CLI |
ARC hosts the runtime. AFS, Blocklet, and identity are primary developer surfaces. AFS UI is the lens that connects AFS resources to AUP and Web Device.
Decision table
| You are trying to… | Correct layer | Common mistake |
|---|---|---|
| List or write a path, mount a provider | AFS | Assuming every mount supports search or exec |
| Describe buttons, forms, and state for an interactive app | AUP | Copying Web components into the AUP semantic contract |
| Publish pages, posts, or a marketing site | Web Device | Treating layout AUP as a full interactive session |
| Ship an installable unit with config and surfaces | Blocklet | Calling a single .aup file “the Blocklet” |
| Know who signed in and which user data they may see | Identity | Trusting a path segment that looks like a DID |
| Understand how UI and AFS fit without picking a target yet | AFS UI (this board) | Inventing a third authoring product |
Run arc service / arc blocklet / arc afs | ARC CLI | Treating CLI help as the only product contract |
Composition, not collapse
A Blocklet often uses AFS providers, AUP apps, and Web Device sites. That composition does not merge their contracts:
- Web Device remains an AFS provider (
@aigne/afs-web-device) that renders site trees. - Interactive AUP runs through the UI runtime (
@aigne/afs-ui) and AUP types (@aigne/afs-aup). - DID Space (
@aigne/afs-did-space) is a storage provider; session views project caller data into AFS paths.
When two layers disagree in documentation, keep the claim on the layer that owns the behaviour, and link the other for context. Do not “average” them into one API.
Where evidence lives
| Claim type | Prefer |
|---|---|
| Present-tense operation or field | Sibling board + current source/tests for that layer |
| “How layers fit” | This architecture board |
| Old product name | Product lineage |
Classification rules: Contracts and evidence.