Skip to content

Commit 38c712b

Browse files
MartinCastroAlvarezmartin-castro-laminr-aiclaude
authored
docs: realign all root .md files to the React-super-layer scope (#544) (#547)
Direct owner directive (2026-05-28): "make sure these md files are congruent with the scope of this library now." The project just split into three repos — `django-admin-rest-api` owns the JSON API surface (now on PyPI), this repo becomes the React SPA super-layer on top of it, and `django-admin-mcp` (planned) will expose the same ModelAdmin-driven functionality over MCP. Per-file scope notices + factual fixes: - README.md: lead with the two-line install (both `INSTALLED_APPS` entries + URL include) and a 3-repo table. Drop the stale Playwright reference for screenshots (owner pref: no e2e tooling). - ARCHITECTURE.md: open with the 3-repo split + a scope notice that `django_admin_react/api/` content is transient during #544. - PRODUCT_VISION.md: add "What's in this repo vs the API repo vs the MCP repo" section. - ONBOARDING.md: install snippet shows both apps (`django_admin_rest_api` + `django_admin_react`) with a "why two apps?" explainer. - CLAUDE.md: scope notice + replace the multi-agent / worktree mode with the new **sole-agent, no-worktrees** directive from the same message; cross-repo discipline (API work → API repo). - API_CONTRACT.md: rewritten as a pointer to the canonical API-repo contract; notes the transient copy at `docs/api-contract.md`. - SECURITY.md: responsibility matrix splitting API-level concerns (API repo) from SPA-level concerns (here); transitional rules clarified. - TESTING.md: API endpoint tests now belong in the API repo; this repo's tests cover frontend (vitest) + SPA-specific backend. Removed the Playwright e2e layer entirely (owner pref). - CONTRIBUTING.md: "Where does my contribution belong?" routing for all three repos. - DESIGN_SYSTEM.md: scope note (UI design system covers the SPA only). - CHANGELOG.md: `[Unreleased] → Architecture` entry for the 3-repo split and #544 / Phase 1. - ACCEPTANCE.md: scope note — API-wire criteria move to the API repo's ACCEPTANCE; SPA-side criteria stay here. No code changes; CI gate covers tests/build, which this PR doesn't touch. Refs #544 Co-authored-by: Martin Castro Laminrs <mcastro@laminr.ai> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent a0121de commit 38c712b

12 files changed

Lines changed: 328 additions & 94 deletions

‎ACCEPTANCE.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,24 @@
33
This file defines the **measurable, testable** criteria the project
44
must meet to be considered "production-ready" by each owning role.
55

6+
> ### Scope (post-#544)
7+
>
8+
> This file covers the **React SPA super-layer**. Acceptance criteria
9+
> that test API-wire behaviour (auth, authz, queryset, serializer
10+
> denylist, write-form enforcement, the §6 per-endpoint matrix, the
11+
> wire contract) live in the
12+
> **[`django-admin-rest-api`](https://github.com/MartinCastroAlvarez/django-admin-api)
13+
> repo's `ACCEPTANCE.md`** from this point forward — the API repo owns
14+
> the API. During [META #544](https://github.com/MartinCastroAlvarez/django-admin-react/issues/544)
15+
> the API-side criteria below still apply **here** until the local
16+
> `django_admin_react/api/` tree is removed (Phase 3); they apply in
17+
> the API repo permanently.
18+
>
19+
> The SPA-side criteria — plug-and-play install, responsive UI,
20+
> accessibility, SPA navigation, visual consistency, extensibility UX,
21+
> pre-built bundle integrity, frontend test coverage — stay here as
22+
> the durable record.
23+
624
**Coordination protocol** — every agent role owns its own section:
725

826
- §2 **Product / UX** — owned by `claude-pm-ux-opus47` (this PR).

‎API_CONTRACT.md‎

Lines changed: 48 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,53 @@
11
# API_CONTRACT.md
22

3-
This file is a **pointer** to the canonical API contract document. The
4-
long-form contract lives under [`docs/api-contract.md`](docs/api-contract.md)
5-
so it can sit next to the rest of the long-form docs.
6-
7-
This top-level pointer exists so that a contributor scanning the repo
8-
root finds the contract without having to dig.
9-
10-
> If you are an AI agent: the canonical contract is
11-
> [`docs/api-contract.md`](docs/api-contract.md). Any change to the
12-
> wire shape **must** update that file in the same PR, per
13-
> [`ACCEPTANCE.md`](ACCEPTANCE.md) §3.4 C-1.
14-
15-
## What the contract covers
16-
17-
- HTTP endpoints under the consumer-chosen mount (default examples
18-
use `/admin-react/api/v1/`).
19-
- Request and response JSON shapes.
20-
- The closed v1 field-type vocabulary (`string`, `integer`,
21-
`decimal`, `boolean`, `date`, `datetime`, `uuid`, `choice`,
22-
`foreignkey`, `unsupported`).
23-
- The uniform error envelope.
24-
- Pagination, ordering, search rules.
25-
- Forwards-compatibility rules (additive only within `api/v1/`).
26-
27-
## Stability promise
28-
29-
- Within `api/v1/`: **additive only**. New optional response fields
30-
and query params are fine; renames / removes / type changes are
31-
not — they require a new namespace (`api/v2/`).
32-
- Breaking changes are documented in the top-level `CHANGELOG.md`
33-
(added with the first release) and require a major version bump
34-
from `1.0.0` onward.
35-
36-
## Who owns this
37-
38-
- **Specification** — Software Architect agent
39-
([`docs/agents/software-architect/`](docs/agents/software-architect/)).
40-
- **Implementation** — Architect, with Security review for
41-
permission and serialization paths.
42-
- **Consumer expectations** — Product Manager agent verifies the
43-
contract supports the documented user flows
44-
([`docs/ux/primary-flows.md`](docs/ux/primary-flows.md)).
3+
> ### The canonical API contract lives in the API repo (post-#544)
4+
>
5+
> The JSON REST API surface — every endpoint shape, the field-type
6+
> vocabulary, the uniform error envelope, pagination / ordering / search
7+
> rules, and the additive-only forward-compatibility promise — is the
8+
> **`django-admin-rest-api`** package's contract. The canonical document
9+
> is therefore in the API repo, not here.
10+
>
11+
> **Read it at:** [`MartinCastroAlvarez/django-admin-api → docs/api-contract.md`](https://github.com/MartinCastroAlvarez/django-admin-api/blob/main/docs/api-contract.md)
12+
>
13+
> Any change to the wire shape must land in that repo's PR. This SPA
14+
> repo consumes the contract; it does not own it.
15+
16+
## Why this pointer still exists
17+
18+
A contributor or AI agent scanning this repo's root might still expect
19+
an `API_CONTRACT.md` here. This file stays as a one-click hop to the
20+
real document so nobody is confused about where to look.
21+
22+
## During the #544 migration
23+
24+
While [META #544](https://github.com/MartinCastroAlvarez/django-admin-react/issues/544)
25+
is in flight, a copy of the contract still lives temporarily at
26+
[`docs/api-contract.md`](docs/api-contract.md). That copy is being
27+
retired phase-by-phase as the local `django_admin_react/api/` tree is
28+
removed. **Treat the API repo's copy as authoritative** from this point
29+
forward — any drift between the two is a bug in the migration, not a
30+
license to fork the contract.
31+
32+
## What stays in this repo (SPA side)
33+
34+
- The TypeScript mirror of the contract under
35+
[`frontend/packages/api/src/contract.ts`](frontend/packages/api/src/contract.ts).
36+
It must match the canonical API-repo document; the codebase enforces
37+
this via the boundary lint and typecheck gates.
38+
- The SPA's consumer of each endpoint (React Query hooks, `@dar/data`,
39+
`@dar/api`). These call the wire shape, they don't define it.
40+
41+
## Stability promise (unchanged)
42+
43+
- Within `api/v1/`: **additive only.** New optional response fields and
44+
query params are fine; renames / removes / type changes are not — they
45+
require a new namespace (`api/v2/`).
46+
- Breaking changes appear in the API repo's `CHANGELOG.md` and require a
47+
major version bump from `1.0.0` onward.
4548

4649
## Tests asserting the contract
4750

48-
See [`TESTING.md`](TESTING.md) §3 (mandatory test matrix). Integration
49-
tests under `tests/test_*.py` assert each endpoint's request/response
50-
shape against the contract.
51+
The API repo owns the request/response shape tests. This repo's tests
52+
exercise the SPA's behaviour against the contract (via the same wire,
53+
read by the TS mirror). See [`TESTING.md`](TESTING.md) §3.

‎ARCHITECTURE.md‎

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,42 @@
11
# Architecture
22

3-
`django-admin-react` is a Django package that exposes a stable, conservative
4-
REST API on top of `django.contrib.admin` and ships a pre-built React
5-
single-page application that consumes it. The Django ModelAdmin is the **only
6-
source of truth** for permissions, querysets, forms, and field configuration.
7-
8-
> This document is the architectural contract. Any change that conflicts with
9-
> it must update this file in the same PR and be recorded in
10-
> [`docs/agents/decisions.md`](docs/agents/decisions.md).
3+
`django-admin-react` is a Django package that ships a pre-built React
4+
single-page application against the **stable, conservative JSON REST API**
5+
exposed by the sibling package
6+
[`django-admin-rest-api`](https://github.com/MartinCastroAlvarez/django-admin-api)
7+
(its own PyPI release). The Django `ModelAdmin` is the **only source of
8+
truth** for permissions, querysets, forms, and field configuration — both
9+
packages honour that contract.
10+
11+
> This document is the architectural contract for the **SPA super-layer**.
12+
> Any change that conflicts with it must update this file in the same PR
13+
> and be recorded in [`docs/agents/decisions.md`](docs/agents/decisions.md).
14+
> The wire-contract document (what the API actually emits / accepts) lives
15+
> in the **API repo** — this file refers to it but does not duplicate it.
16+
17+
> ### Scope (after #544)
18+
>
19+
> The codebase split into **three repos** so each layer can be reasoned about
20+
> and consumed independently:
21+
>
22+
> - **[`django-admin-rest-api`](https://github.com/MartinCastroAlvarez/django-admin-api)**
23+
> — every JSON endpoint, the serializer denylist, the permission gates,
24+
> the wire contract. Same `ModelAdmin`, same permissions, no new features.
25+
> - **`django-admin-react`** *(this repo)* — the **React SPA super-layer**
26+
> on top of that API. Frontend, build pipeline, pre-built assets, the SPA
27+
> mount + PWA glue. **Depends on** `django-admin-rest-api`.
28+
> - **[`django-admin-mcp-api`](https://github.com/MartinCastroAlvarez/django-admin-mcp)**
29+
> ([PyPI](https://pypi.org/project/django-admin-mcp-api/)) — a
30+
> wire-protocol-only MCP adapter over `django-admin-rest-api` (call,
31+
> manifest, …). Reuses the same API classes, adds no new
32+
> functionality / permissions / validation. Installed as a sibling
33+
> dependency of this package.
34+
>
35+
> Migration of the API code out of this repo (Phases 1–7) is tracked in
36+
> [META #544](https://github.com/MartinCastroAlvarez/django-admin-react/issues/544).
37+
> Sections of this document that describe `django_admin_react/api/`
38+
> internals describe **transient** state during that migration; the
39+
> long-term home for those details is the API repo.
1140
1241
---
1342

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,17 @@ version section at release.
1414

1515
## [Unreleased]
1616

17+
### Architecture
18+
- Project scope split into three independently-published, cross-referenced
19+
repos: **`django-admin-rest-api`** owns the JSON API surface (on PyPI),
20+
**`django-admin-react`** *(this repo)* becomes the **React SPA
21+
super-layer** that depends on it, and **`django-admin-mcp-api`** (also
22+
PyPI, `0.1.0a0`) exposes the same `ModelAdmin`-driven REST surface
23+
over MCP — both sibling packages ship as dependencies of this one.
24+
Migration tracked in META #544; Phase 1 added `django-admin-rest-api ^0.1.0a0`
25+
and `django-admin-mcp-api ^0.1.0a0` as dependencies. Root `.md` files
26+
realigned to the new scope in the same release window.
27+
1728
### Security
1829
- A `CharField` the admin masks with `forms.PasswordInput` (e.g. via
1930
`formfield_overrides`) no longer leaks its stored value in the detail

‎CLAUDE.md‎

Lines changed: 53 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,15 +2,42 @@
22

33
This file is the contract between this repository and any Claude (or other
44
AI) agent contributing to it. **Read this file from top to bottom before
5-
doing anything else, every session.** Multiple agents may be working
6-
concurrently — coordination is the only way to avoid stepping on each
7-
other.
5+
doing anything else, every session.**
86

97
> If anything in this file is unclear or seems wrong, do **not** silently
108
> work around it. Add an entry to
119
> [`docs/agents/open-questions.md`](docs/agents/open-questions.md) and pick
1210
> the simpler interpretation.
1311
12+
> ### Scope of this repo (post-#544)
13+
>
14+
> This is the **React SPA super-layer**. The JSON REST API surface — every
15+
> endpoint, the serializer denylist, the permission gates, the wire contract
16+
> — lives in the sibling package
17+
> [`django-admin-rest-api`](https://github.com/MartinCastroAlvarez/django-admin-api)
18+
> ([PyPI](https://pypi.org/project/django-admin-rest-api/)) and is pulled
19+
> in as a dependency. The MCP exposure of the same `ModelAdmin`-driven
20+
> functionality lives in
21+
> [`django-admin-mcp-api`](https://pypi.org/project/django-admin-mcp-api/)
22+
> ([`MartinCastroAlvarez/django-admin-mcp`](https://github.com/MartinCastroAlvarez/django-admin-mcp))
23+
> — also `0.1.0a0` on PyPI; shipped as a sibling dependency of this package.
24+
>
25+
> **Practical impact for agents working here:**
26+
>
27+
> 1. Bug fixes / features for any `/api/v1/...` JSON endpoint belong in the
28+
> API repo, not here. If you find such a bug while working in this repo,
29+
> open the issue in the API repo and link it from here. Do **not** add
30+
> a parallel implementation in this repo.
31+
> 2. The local `django_admin_react/api/` tree is **transient** — it is
32+
> being removed in Phases 2-7 of [META #544](https://github.com/MartinCastroAlvarez/django-admin-react/issues/544).
33+
> Don't add new endpoints here.
34+
> 3. SPA work (React components, the PWA, the SPA mount, screenshots,
35+
> static assets, the build pipeline) belongs here.
36+
>
37+
> The mode of execution after the owner's 2026-05-28 directive: **a single
38+
> agent at a time, no worktrees** — work on branches off `main` in the
39+
> primary checkout.
40+
1441
---
1542

1643
## 0. Required reading on session start
@@ -122,17 +149,21 @@ Detailed shape is in [`ARCHITECTURE.md`](ARCHITECTURE.md).
122149

123150
---
124151

125-
## 4. Multi-agent coordination
152+
## 4. Coordination (sole-agent mode — 2026-05-28 directive)
153+
154+
> **Earlier sessions ran a multi-agent swarm in parallel worktrees.**
155+
> The owner ended that mode on 2026-05-28: a **single agent** works in
156+
> the primary checkout, on branches off `main`, **no worktrees**. The
157+
> guidance below is updated for that mode.
126158
127-
Several agents may be running at once. Coordination lives on GitHub —
128-
not in committed markdown — so the surface stays searchable, indexed,
129-
and notification-driven.
159+
All coordination still lives on GitHub — not in committed markdown — so
160+
the surface stays searchable, indexed, and notification-driven.
130161

131-
1. **Claim a Project board card before opening a PR.** Look at the
162+
1. **Track work as Issues / Project board cards.** Look at the
132163
[Project board](https://github.com/users/MartinCastroAlvarez/projects/3)
133164
and the open [Issues](https://github.com/MartinCastroAlvarez/django-admin-react/issues).
134-
Assign yourself (or post a claim comment on the issue) before you
135-
start. If the issue doesn't exist yet, open one first.
165+
For new work, open the issue first; for in-flight work, leave a
166+
status comment so the audit trail is real-time.
136167
2. **Use GitHub for everything else:**
137168
- **[Issues](https://github.com/MartinCastroAlvarez/django-admin-react/issues)**
138169
— work tracking. One issue per actionable piece of work.
@@ -147,14 +178,21 @@ and notification-driven.
147178
- [`docs/agents/open-questions.md`](docs/agents/open-questions.md)
148179
— questions awaiting a decision that aren't yet shaped for an
149180
issue or Discussion.
150-
3. **Do not duplicate work.** Before starting, scan the open PR list
151-
and the assigned cards on the board. If someone is already on it,
152-
comment on their PR or their card instead of forking the effort.
153-
4. **Public repo, public eyes.** Everything in this repository
181+
3. **Branch off `main` directly** — no `git worktree`. One branch per
182+
PR; squash-merge through the GitHub UI (or `gh pr merge --squash`)
183+
when CI is green and the review is on the record.
184+
4. **Cross-repo discipline.** API work (any `/api/v1/...` endpoint, the
185+
wire contract, the serializer denylist, the permission gates) goes
186+
to the **`django-admin-rest-api` repo**, not here. MCP work to the
187+
`django-admin-mcp` repo (PyPI: `django-admin-mcp-api`). This repo owns the **React SPA**
188+
super-layer and its docs only — see the scope notice at the top of
189+
this file.
190+
5. **Public repo, public eyes.** Everything in this repository
154191
(`docs/`, commits, PR descriptions, commit messages, Issues,
155192
Discussions) is published. Do not paste secrets, tokens,
156193
transcripts, private user data, or anything that wouldn't survive
157-
a public audit.
194+
a public audit. The PAT embedded in the local git remote is a
195+
build-time convenience — treat it like a `.env` secret.
158196

159197
---
160198

‎CONTRIBUTING.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,26 @@ Thank you for considering a contribution! This file explains the workflow
44
for humans. The companion file [`CLAUDE.md`](CLAUDE.md) lays out the same
55
contract for AI coding agents working in this repository.
66

7+
> ### Where does my contribution belong? (post-#544)
8+
>
9+
> The project is three repos with separate scopes — please open the PR
10+
> in the right one:
11+
>
12+
> - **API behaviour, wire shape, permission gates, serializer denylist,
13+
> any `/api/v1/...` endpoint** → [`MartinCastroAlvarez/django-admin-api`](https://github.com/MartinCastroAlvarez/django-admin-api)
14+
> ([PyPI `django-admin-rest-api`](https://pypi.org/project/django-admin-rest-api/)).
15+
> - **React SPA, components, hooks, pre-built assets, PWA, the SPA
16+
> mount, screenshots, this repo's docs** → here.
17+
> - **MCP exposure of the same `ModelAdmin`-driven functionality** →
18+
> [`MartinCastroAlvarez/django-admin-mcp`](https://github.com/MartinCastroAlvarez/django-admin-mcp)
19+
> ([PyPI `django-admin-mcp-api`](https://pypi.org/project/django-admin-mcp-api/)).
20+
>
21+
> If you're not sure, open an [Issue](https://github.com/MartinCastroAlvarez/django-admin-react/issues/new)
22+
> first and we'll route it. While [META #544](https://github.com/MartinCastroAlvarez/django-admin-react/issues/544)
23+
> is in flight, a copy of the API code still lives in
24+
> `django_admin_react/api/` here — please don't add new API features
25+
> to that copy; raise them in the API repo.
26+
727
## 1. Before you start
828

929
Read, in order:

‎DESIGN_SYSTEM.md‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,19 @@
33
Owner: Product / UX role.
44
Implementing role: Frontend Engineer agent — see open Issues on the
55
[Project board](https://github.com/users/MartinCastroAlvarez/projects/3).
6-
Last reviewed: 2026-05-25.
6+
Last reviewed: 2026-05-28.
77

88
> The design system is **opinionated, closed, and small**. The point
99
> is not to give us range — it's to make every screen consistent for
1010
> a Django developer who never touched React.
1111
12+
> ### Scope
13+
>
14+
> This design system covers the **React SPA** shipped by this repo. The
15+
> sibling [`django-admin-rest-api`](https://github.com/MartinCastroAlvarez/django-admin-api)
16+
> package has no UI — it serves JSON — so it has no design system of
17+
> its own. Any UX-shaped decision lives here.
18+
1219
If a screen needs a token that does not appear here, propose an
1320
addition via [`docs/agents/open-questions.md`](docs/agents/open-questions.md)
1421
rather than inventing a one-off.

‎ONBOARDING.md‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,14 +47,23 @@ INSTALLED_APPS = [
4747
"django.contrib.sessions",
4848
"django.contrib.messages",
4949
"django.contrib.staticfiles",
50-
"django_admin_react", # ← add this
50+
"django_admin_rest_api", # ← the JSON REST API (sibling package, auto-installed as a dependency)
51+
"django_admin_react", # ← this package — the React SPA
5152
# ... your own apps
5253
]
5354
```
5455
5556
That's the whole settings change. No `MIDDLEWARE` change required —
5657
we rely on the same session and CSRF middleware Django's admin uses.
5758

59+
> **Why two apps?** `pip install django-admin-react` pulls in
60+
> [`django-admin-rest-api`](https://pypi.org/project/django-admin-rest-api/)
61+
> automatically (it's a declared dependency). The two `INSTALLED_APPS`
62+
> entries are the **only** thing you do differently — the API and the
63+
> SPA are otherwise transparent to your project. See
64+
> [`PRODUCT_VISION.md`](PRODUCT_VISION.md) for why we ship as two
65+
> packages.
66+
5867
### Step 3 — Mount the URLs wherever you want (15 seconds)
5968

6069
```python

0 commit comments

Comments
 (0)