Skip to content

Commit d40c4b3

Browse files
bartstcbartstc
committed
docs: update docs
1 parent 69547a2 commit d40c4b3

3 files changed

Lines changed: 103 additions & 0 deletions

File tree

‎docs/architecture.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,30 @@ Each feature follows feature slice architecture patterns with four layers:
7171

7272
**Cross-slice primitives:** `features/auth/` and `features/authv2/` are cross-cutting concerns (identity, permissions, auth state). Any feature slice may import from them.
7373

74+
```text
75+
┌──────────────────────────────────────────────────────────────────────┐
76+
│ components/ (UI, presentational, no business logic) │
77+
└────────────────────────┬──────────────────────┬──────────────────────┘
78+
│ │
79+
▼ ▼
80+
┌───────────────────────────────────┐ ┌─────────────────────────────────────────┐
81+
│ application/ (hooks, FSMs, │ │ providers/ (query/mutation hooks, │
82+
│ stores, form validation) │ │ DTO → domain mapping) │
83+
└──────────────────┬────────────────┘ └───────────────┬─────────────────────────┘
84+
└──────────────┬───────────────────┘ │
85+
▼ │
86+
┌──────────────────────────────┐ │
87+
│ models/ (domain types only) │ │
88+
└──────────────────────────────┘ │
89+
▼
90+
┌─────────────────────────────┐
91+
│ lib/api/ (queryOptions, │
92+
│ mutations, DTOs) │
93+
└─────────────────────────────┘
94+
```
95+
96+
![Layers](./assets/layers.png)
97+
7498
### Sub-feature Slices
7599

76100
When a feature grows to contain multiple distinct domain sub-areas, each sub-area becomes a **sub-feature slice** — a nested directory with its own four-layer structure (`components/`, `application/`, `providers/`, `models/`).
@@ -79,6 +103,25 @@ The parent feature's layers hold code that is either reusable across sub-feature
79103

80104
The same layer dependency rules apply within sub-feature slices. Additionally, sub-feature layers may import from the parent feature's same or lower layers. Sub-feature slices **may not import from sibling sub-feature slices**.
81105

106+
```text
107+
features/marketing/
108+
├── components/ ← shared across sub-features
109+
├── providers/ ←┐ parent layers accessible
110+
├── models/ ←┘ from sub-features (same/lower only)
111+
│
112+
├── rating/ ✗ cannot import from reviews/
113+
│ ├── components/
114+
│ ├── application/
115+
│ ├── providers/
116+
│ └── models/
117+
│
118+
└── reviews/ ✗ cannot import from rating/
119+
├── components/
120+
├── application/
121+
├── providers/
122+
└── models/
123+
```
124+
82125
## API Library
83126

84127
`src/lib/api/` is the global home for all HTTP logic: `queryOptions` factories, loaders, mutation hooks, query keys, domain errors, and DTOs, organised by resource. Query files expose `queryOptions` factories (no `useQuery` hooks — hook composition belongs in `providers/`). Feature `providers/` compose hooks on top of those factories and re-export them for feature slice. New API logic always goes in `src/lib/api/` first, then gets exposed through the relevant feature's `providers/`.
@@ -92,6 +135,22 @@ The same layer dependency rules apply within sub-feature slices. Additionally, s
92135
| DTO interface | `-dto.ts` | `cart-product-dto.ts` |
93136
| Query keys | `-query-keys.ts` | `cart-query-keys.ts` |
94137

138+
```text
139+
src/lib/api/
140+
cart-products-query.ts (queryOptions factory)
141+
add-to-cart-mutation.ts (mutationOptions factory)
142+
cart-product-dto.ts (DTO types)
143+
│
144+
▼
145+
features/carts/providers/
146+
use-cart-products-query.ts (composes hook + maps DTO → domain model)
147+
use-add-to-cart-mutation.ts
148+
│
149+
▼
150+
features/carts/components/
151+
CartList.tsx (consumes only through providers/)
152+
```
153+
95154
## Key Patterns
96155

97156
| Pattern | Description |

‎docs/assets/layers.png‎

220 KB
Loading

‎docs/spec-driven-development.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,23 @@ skills/
5050
rules/ ← One file per building block (full pattern + example)
5151
```
5252

53+
```
54+
CLAUDE.md ──────────────────► when to spec / plan-mode rules
55+
│
56+
▼
57+
writing-spec/SKILL.md ──────► four-phase gated workflow
58+
│
59+
├──► spec-template.md ──► section structure (Meta, R1…Rn, tasks…)
60+
│
61+
├──► building-blocks/
62+
│ SKILL.md ────────► catalog index (block name + layer)
63+
│ rules/*.md ───────► full pattern per block (read at impl time)
64+
│
65+
├──► architecture.md ────► layer rules, state mgmt, project structure
66+
│
67+
└──► specs/lessons.md ───► accumulated learnings (feedback loop)
68+
```
69+
5370
The flow between these files:
5471

5572
1. **CLAUDE.md** tells the agent _when_ to write a spec (5+ files or 5+ decisions) and establishes the plan-mode-first workflow.
@@ -69,6 +86,33 @@ Every spec follows a fixed section structure defined in `docs/spec-template.md`.
6986

7087
Status tracking table — `draft` → `review` → `approved` → `implementing` → `done` → `archived`. Keeps the spec lifecycle visible.
7188

89+
```
90+
┌─────────────────────────────────────────────────┐
91+
│ Session: Spec Writing │
92+
│ (writing-spec skill, four-phase gated flow) │
93+
│ │
94+
│ draft ──► review ──► approved │
95+
│ ▲ │ │
96+
│ └───────────┘ (revisions loop back) │
97+
└───────────────────────────┬─────────────────────┘
98+
│
99+
▼
100+
┌─────────────────────────────────────────────────┐
101+
│ Session: Implementation │
102+
│ (building-blocks skill, task by task) │
103+
│ │
104+
│ approved ──► implementing ──► done │
105+
└───────────────────────────┬─────────────────────┘
106+
│
107+
▼
108+
┌─────────────────────────────────────────────────┐
109+
│ Session: Tests │
110+
│ (test-building-blocks skill) │
111+
│ │
112+
│ done ──► testing ──► archived │
113+
└─────────────────────────────────────────────────┘
114+
```
115+
72116
### Section 1: Goal & Context (required)
73117

74118
2–5 sentences answering _what problem does this solve and why now_. Constrains intent, not approach. The agent reads this to understand the purpose — if it can't explain the goal, the feature isn't well enough defined.

0 commit comments

Comments
 (0)