Architecture
Architectural constraints for your project
The rule
This is the whole text, exactly as your agent receives it. Nothing is held back for the paid tier.
Full context: docs/architecture.md.
Layers
UI → hooks → services → clients / SDKsDependencies point one way only. A service never imports a component; a client never imports a service. If you need the reverse, invert it with a callback or an event rather than reaching back up.
Where things go
| Kind of code | Lives in | | --- | --- | | Screens and components | The feature's own folder | | Reusable stateful logic | hooks/ within the feature | | Business rules, API access | services/ | | Third-party SDK setup | A single client module per SDK | | Shared primitives | The shared location, after the third use |
Third-party SDKs
Each SDK is initialised in exactly one place and accessed through a thin project wrapper. Components never import a vendor SDK directly.
This is not ceremony: it is what makes the SDK mockable in tests, replaceable without touching feature code, and greppable when its API changes.
State
- Server state and client state are different things — do not store fetched data in the same place as UI state.
- Derive rather than duplicate. Two fields that must agree will eventually disagree.
- Keep state as close to where it is used as possible; lift only when a second consumer genuinely appears.
Adding a feature
1. Create the feature folder with its screens, hooks and services. 2. Put anything crossing a boundary behind a service. 3. Add the tests described in docs/testing.md. 4. If it introduces an SDK, a variable, or a new flow, update docs/.
6 formats, one per tool
Each tab is the file that tool actually reads, at the path it actually looks in. Knowing where each one looks is most of the work of supporting it.
---
description: Architectural constraints for your project
alwaysApply: true
---
# Architecture
Full context: `docs/architecture.md`.
## Layers
```
UI → hooks → services → clients / SDKs
```
Dependencies point one way only. A service never imports a component; a client
never imports a service. If you need the reverse, invert it with a callback or
an event rather than reaching back up.
## Where things go
| Kind of code | Lives in |
| --- | --- |
| Screens and components | The feature's own folder |
| Reusable stateful logic | `hooks/` within the feature |
| Business rules, API access | `services/` |
| Third-party SDK setup | A single client module per SDK |
| Shared primitives | The shared location, after the third use |
## Third-party SDKs
Each SDK is initialised in exactly one place and accessed through a thin project
wrapper. Components never import a vendor SDK directly.
This is not ceremony: it is what makes the SDK mockable in tests, replaceable
without touching feature code, and greppable when its API changes.
## State
- Server state and client state are different things — do not store fetched
data in the same place as UI state.
- Derive rather than duplicate. Two fields that must agree will eventually
disagree.
- Keep state as close to where it is used as possible; lift only when a second
consumer genuinely appears.
## Adding a feature
1. Create the feature folder with its screens, hooks and services.
2. Put anything crossing a boundary behind a service.
3. Add the tests described in `docs/testing.md`.
4. If it introduces an SDK, a variable, or a new flow, update `docs/`.
Hand-written by the module author, frontmatter and all. It is the source the four derived formats are rendered from, so a correction lands here first.
Advisory history
Every time this rule turned out to be wrong, and what we did about it.
This rule has been accurate since it was published. That is a fact about the rule, not a promise about the future — which is the whole reason this section exists.
Pro tells you the day a correction lands that affects a repo you actually have.
See what Pro adds →Every generated project gets this rule automatically — there is nothing to add. The wizard picks the rest of the stack with you and leaves a manifest, so check can tell you when any of it drifts.