create-groundwork 0.0.0-stage → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +87 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +63 -0
- package/README.md +81 -2
- package/dist/commands.js +294 -0
- package/dist/create.js +4 -0
- package/dist/engine.js +124 -0
- package/dist/groundwork.js +4 -0
- package/dist/profiles.js +77 -0
- package/dist/prompter.js +42 -0
- package/dist/scaffold.js +274 -0
- package/dist/text.js +31 -0
- package/package.json +48 -4
- package/template/.github/README.md +14 -0
- package/template/.github/pull_request_template.md +22 -0
- package/template/.github/workflows/docs-check.yml +23 -0
- package/template/AGENTS.md +88 -0
- package/template/BUILD.md +27 -0
- package/template/LICENSE.md +5 -0
- package/template/PROJECT.md +26 -0
- package/template/README.md +40 -0
- package/template/_gitignore +26 -0
- package/template/config/README.md +3 -0
- package/template/docs/README.md +53 -0
- package/template/docs/architecture/REPOSITORY_STRUCTURE.md +37 -0
- package/template/docs/architecture/SYSTEM_DESIGN.md +30 -0
- package/template/docs/architecture/adr/0000-template.md +28 -0
- package/template/docs/architecture/adr/README.md +11 -0
- package/template/docs/architecture/system-design/README.md +15 -0
- package/template/docs/engineering/SECURITY.md +22 -0
- package/template/docs/engineering/TEST_STRATEGY.md +33 -0
- package/template/docs/examples/EXAMPLE.md +56 -0
- package/template/docs/examples/PROFILES.md +75 -0
- package/template/docs/plans/README.md +10 -0
- package/template/docs/plans/_template/PLAN.md +39 -0
- package/template/docs/product/PRD.md +39 -0
- package/template/docs/product/SPEC.md +63 -0
- package/template/docs/product/specs/README.md +37 -0
- package/template/docs/product/specs/_template/SPEC.md +78 -0
- package/template/infrastructure/README.md +3 -0
- package/template/profiles/README.md +96 -0
- package/template/profiles/ai-systems/README.md +44 -0
- package/template/profiles/ai-systems/profile.json +35 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/EVALUATION.md +35 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/MODEL_INTEGRATION.md +37 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/RETRIEVAL.md +26 -0
- package/template/profiles/ai-systems/templates/docs/ai-systems/SAFETY.md +35 -0
- package/template/profiles/application/README.md +43 -0
- package/template/profiles/application/profile.json +47 -0
- package/template/profiles/application/templates/docs/application/RELEASES.md +28 -0
- package/template/profiles/backend-api/README.md +40 -0
- package/template/profiles/backend-api/profile.json +42 -0
- package/template/profiles/backend-api/templates/docs/backend-api/DATA.md +27 -0
- package/template/profiles/core/profile.json +74 -0
- package/template/profiles/core/templates/docs/architecture/contracts/README.md +11 -0
- package/template/profiles/core/templates/docs/architecture/system-design/01-system-overview.md +29 -0
- package/template/profiles/core/templates/docs/architecture/system-design/02-domain-and-state-model.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/03-behaviour-and-business-rules.md +29 -0
- package/template/profiles/core/templates/docs/architecture/system-design/04-architecture-and-interfaces.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/05-execution-and-resilience.md +30 -0
- package/template/profiles/core/templates/docs/architecture/system-design/06-operations-and-scalability.md +27 -0
- package/template/profiles/core/templates/docs/architecture/system-design/07-ui-and-interaction-mapping.md +35 -0
- package/template/profiles/core/templates/docs/design/DESIGN.md +202 -0
- package/template/profiles/web/README.md +41 -0
- package/template/profiles/web/profile.json +34 -0
- package/template/profiles/web/templates/docs/web/CONTENT.md +39 -0
- package/template/profiles/web/templates/docs/web/SEO.md +35 -0
- package/template/scaffold-manifest.json +77 -0
- package/template/scripts/README.md +29 -0
- package/template/scripts/check_docs.py +989 -0
- package/template/scripts/groundwork.py +716 -0
- package/template/src/README.md +3 -0
- package/template/tests/README.md +3 -0
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Client Releases
|
|
2
|
+
|
|
3
|
+
> Application profile, optional. Create this when the app ships as an installed client (app store, desktop installer), so older versions stay in use after each release. Environments and server deployment stay in `docs/architecture/system-design/06-operations-and-scalability.md`, if the project has it.
|
|
4
|
+
|
|
5
|
+
## Channels
|
|
6
|
+
Where the app is distributed (app stores, installers, company distribution), and each channel's review, signing and approval steps.
|
|
7
|
+
|
|
8
|
+
## Versioning
|
|
9
|
+
How version and build numbers are set, and what a version number promises to users.
|
|
10
|
+
|
|
11
|
+
## Supported versions
|
|
12
|
+
The oldest version still supported, and how people on older versions are asked or required to update.
|
|
13
|
+
|
|
14
|
+
## Version skew
|
|
15
|
+
Older clients keep calling the backend after a release. How the interfaces they use stay compatible, and for how long. Link the contracts in `docs/architecture/contracts/` if the project has them.
|
|
16
|
+
|
|
17
|
+
## Rollout
|
|
18
|
+
Staged rollouts, feature flags (switches that turn a feature on or off without a new release) and over-the-air updates, where the platform allows them.
|
|
19
|
+
|
|
20
|
+
## Rollback
|
|
21
|
+
A shipped client cannot be recalled. How a bad release is contained: switch the feature off on the server, ship a fixed release, or require an update.
|
|
22
|
+
|
|
23
|
+
## Release checklist
|
|
24
|
+
What must be true before each release.
|
|
25
|
+
|
|
26
|
+
- [ ] Critical journeys pass end to end on every supported platform.
|
|
27
|
+
- [ ] The backend still works with the oldest supported version.
|
|
28
|
+
- [ ] Store listing, screenshots and privacy details are up to date.
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# Backend/API Profile
|
|
2
|
+
|
|
3
|
+
For backend services, APIs, workers, distributed systems and integrations. When it applies, which documents it adds and which checks it needs are declared in [profile.json](profile.json).
|
|
4
|
+
|
|
5
|
+
## Where each concern lives
|
|
6
|
+
|
|
7
|
+
| Concern | Lives in |
|
|
8
|
+
|---|---|
|
|
9
|
+
| Domain model: concepts, ownership, state | `docs/architecture/system-design/02-domain-and-state-model.md` |
|
|
10
|
+
| Rules and invariants | `docs/architecture/system-design/03-behaviour-and-business-rules.md`, with the ID'd rules in `SPEC.md` and feature specs |
|
|
11
|
+
| Components, boundaries, interface summary | `docs/architecture/system-design/04-architecture-and-interfaces.md` |
|
|
12
|
+
| Detailed API and event contracts (optional) | `docs/architecture/contracts/` |
|
|
13
|
+
| Concurrency, failure, retries, recovery | `docs/architecture/system-design/05-execution-and-resilience.md` |
|
|
14
|
+
| Deployment, observability, capacity | `docs/architecture/system-design/06-operations-and-scalability.md` |
|
|
15
|
+
| Data stores, migrations, backups, retention (optional) | `docs/backend-api/DATA.md` |
|
|
16
|
+
| Access control, secrets, data protection | `docs/engineering/SECURITY.md` |
|
|
17
|
+
|
|
18
|
+
## Engineering standards
|
|
19
|
+
|
|
20
|
+
Defaults for the services. A project can override any of them with a requirement in `SPEC.md` or an accepted ADR.
|
|
21
|
+
|
|
22
|
+
- Check every input at the service boundary, and return errors in one documented shape.
|
|
23
|
+
- Every operation a client may retry is idempotent (safe to run twice), or the contract says it is not.
|
|
24
|
+
- Every outgoing call has a timeout. Retries back off and have a limit.
|
|
25
|
+
- Public interfaces change compatibly: add, don't remove or rename. Breaking changes need a new version and an ADR.
|
|
26
|
+
- Schema migrations can be applied without downtime and can be undone, or the plan says why not.
|
|
27
|
+
- Logs are structured and leave out secrets and personal data. Each request can be traced across components.
|
|
28
|
+
- Each service has a health check and the alerts listed in `06-operations-and-scalability.md`.
|
|
29
|
+
|
|
30
|
+
## Agent instructions
|
|
31
|
+
|
|
32
|
+
- Before changing an interface, read its section in `04-architecture-and-interfaces.md` and its contract, if there is one. Check who consumes it.
|
|
33
|
+
- When you change stored data, update `02-domain-and-state-model.md` and, if it exists, `DATA.md`, and write the migration plan in the change's plan.
|
|
34
|
+
- When you add a dependency on another service, add its failure row to `05-execution-and-resilience.md`.
|
|
35
|
+
- Treat a missing timeout, an unbounded retry or an unchecked input as a bug.
|
|
36
|
+
|
|
37
|
+
## Composing with other profiles
|
|
38
|
+
|
|
39
|
+
- **With Application:** see the Application profile — one copy of the shared design documents, with client and services as separate components.
|
|
40
|
+
- **With AI Systems:** model calls are outgoing integrations. They follow this profile's rules on timeouts, retries and failure, plus the AI-specific rules in `docs/ai-systems/`.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schema": 1,
|
|
3
|
+
"id": "backend-api",
|
|
4
|
+
"name": "Backend/API",
|
|
5
|
+
"purpose": "Backend services, APIs, workers, distributed systems and integrations. Adds domain modelling, interface contracts, data architecture, resilience and day-to-day operations.",
|
|
6
|
+
"use_when": [
|
|
7
|
+
"The project owns server-side logic or data that other software depends on: its own clients, other teams or outside partners.",
|
|
8
|
+
"Failures, retries, concurrency or data consistency need deliberate design.",
|
|
9
|
+
"The team deploys, monitors and keeps services running."
|
|
10
|
+
],
|
|
11
|
+
"not_when": [
|
|
12
|
+
"The backend is a hosted service used as-is (a CMS, a database service, a form handler) with no logic of your own. Describe it in SYSTEM_DESIGN.md.",
|
|
13
|
+
"A handful of serverless functions only forward requests. Describe them in the other profile's architecture document.",
|
|
14
|
+
"A server framework is in use. Technology alone never activates a profile."
|
|
15
|
+
],
|
|
16
|
+
"requires": [],
|
|
17
|
+
"incompatible_with": [],
|
|
18
|
+
"documents": [
|
|
19
|
+
{ "path": "docs/architecture/system-design/01-system-overview.md", "required": true },
|
|
20
|
+
{ "path": "docs/architecture/system-design/02-domain-and-state-model.md", "required": true },
|
|
21
|
+
{ "path": "docs/architecture/system-design/03-behaviour-and-business-rules.md", "required": true },
|
|
22
|
+
{ "path": "docs/architecture/system-design/04-architecture-and-interfaces.md", "required": true },
|
|
23
|
+
{ "path": "docs/architecture/system-design/05-execution-and-resilience.md", "required": true },
|
|
24
|
+
{ "path": "docs/architecture/system-design/06-operations-and-scalability.md", "required": true },
|
|
25
|
+
{ "path": "docs/engineering/SECURITY.md", "required": true },
|
|
26
|
+
{ "path": "docs/engineering/TEST_STRATEGY.md", "required": true },
|
|
27
|
+
{
|
|
28
|
+
"path": "docs/architecture/contracts/README.md",
|
|
29
|
+
"required": false,
|
|
30
|
+
"when": "An API or event stream has several consumers, outside teams or versioning needs."
|
|
31
|
+
},
|
|
32
|
+
{
|
|
33
|
+
"path": "docs/backend-api/DATA.md",
|
|
34
|
+
"required": false,
|
|
35
|
+
"when": "The system has more than one data store, migrates live data, or must meet backup, retention or residency rules."
|
|
36
|
+
}
|
|
37
|
+
],
|
|
38
|
+
"checks": [
|
|
39
|
+
{ "name": "Integration tests", "what": "Services run against their real dependencies (database, queues) or faithful stand-ins." },
|
|
40
|
+
{ "name": "API compatibility", "what": "Changes to public interfaces are checked for breaking changes before release." }
|
|
41
|
+
]
|
|
42
|
+
}
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# Data Architecture
|
|
2
|
+
|
|
3
|
+
> Backend/API profile, optional. Create this when the system has more than one data store, migrates live data, or must meet backup, retention or residency rules. The concepts, their owners and their states stay in `docs/architecture/system-design/02-domain-and-state-model.md`; this document covers where the data physically lives and how it is kept safe over time.
|
|
4
|
+
|
|
5
|
+
## Data stores
|
|
6
|
+
| Store | Kind | Data it holds | Owning component | Source of truth? |
|
|
7
|
+
|---|---|---|---|---|
|
|
8
|
+
| | | | | |
|
|
9
|
+
|
|
10
|
+
## Data flows
|
|
11
|
+
How data moves between stores and services: copies, caches, search indexes, analytics exports. For each copy, say which side wins when they disagree.
|
|
12
|
+
|
|
13
|
+
## Schema changes and migrations
|
|
14
|
+
How the data's shape changes without downtime or data loss — for example expand then contract: add the new shape, move the data, then remove the old shape. Say how backfills run and how a migration is undone.
|
|
15
|
+
|
|
16
|
+
## Backup and restore
|
|
17
|
+
Recovery point: how much recent data may be lost. Recovery time: how long a restore may take.
|
|
18
|
+
|
|
19
|
+
| Store | Backup frequency | Recovery point | Recovery time | Last restore test |
|
|
20
|
+
|---|---|---|---|---|
|
|
21
|
+
| | | | | |
|
|
22
|
+
|
|
23
|
+
## Retention and deletion
|
|
24
|
+
How long each kind of data is kept, and how it is deleted, including when a user asks. How data is classified lives in `docs/engineering/SECURITY.md`.
|
|
25
|
+
|
|
26
|
+
## Residency and access
|
|
27
|
+
Where the data is physically stored, which legal or contract rules limit that, and who or what may read production data.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
{
|
|
2
|
+
"schema": 1,
|
|
3
|
+
"id": "core",
|
|
4
|
+
"name": "Groundwork Core",
|
|
5
|
+
"purpose": "The base every project gets, whatever it is: project definition, agent instructions, product and system requirements with traceable IDs, the architecture starting point, decisions, plans and the shared checks. Always active; profiles add to it and never change it.",
|
|
6
|
+
"documents": [
|
|
7
|
+
{ "path": "PROJECT.md", "required": true },
|
|
8
|
+
{ "path": "AGENTS.md", "required": true },
|
|
9
|
+
{ "path": "BUILD.md", "required": true },
|
|
10
|
+
{ "path": "docs/product/PRD.md", "required": true },
|
|
11
|
+
{ "path": "docs/product/SPEC.md", "required": true },
|
|
12
|
+
{ "path": "docs/architecture/SYSTEM_DESIGN.md", "required": true },
|
|
13
|
+
{
|
|
14
|
+
"path": "docs/engineering/SECURITY.md",
|
|
15
|
+
"required": false,
|
|
16
|
+
"when": "The project handles user data, accounts, payments, secrets or anything worth attacking. Shipped in place; delete it only if none of that applies."
|
|
17
|
+
},
|
|
18
|
+
{
|
|
19
|
+
"path": "docs/engineering/TEST_STRATEGY.md",
|
|
20
|
+
"required": false,
|
|
21
|
+
"when": "The project has code that needs more than one kind of test. Shipped in place."
|
|
22
|
+
},
|
|
23
|
+
{
|
|
24
|
+
"path": "docs/architecture/REPOSITORY_STRUCTURE.md",
|
|
25
|
+
"required": false,
|
|
26
|
+
"when": "You are choosing how to lay out the repository. Shipped in place; delete it once the layout is settled."
|
|
27
|
+
},
|
|
28
|
+
{
|
|
29
|
+
"path": "docs/architecture/system-design/01-system-overview.md",
|
|
30
|
+
"required": false,
|
|
31
|
+
"when": "The system has several actors, external systems or boundaries worth describing beyond the summary in SYSTEM_DESIGN.md."
|
|
32
|
+
},
|
|
33
|
+
{
|
|
34
|
+
"path": "docs/architecture/system-design/02-domain-and-state-model.md",
|
|
35
|
+
"required": false,
|
|
36
|
+
"when": "The system keeps its own data or state with rules about who owns it."
|
|
37
|
+
},
|
|
38
|
+
{
|
|
39
|
+
"path": "docs/architecture/system-design/03-behaviour-and-business-rules.md",
|
|
40
|
+
"required": false,
|
|
41
|
+
"when": "State changes follow rules that must always hold (invariants, transitions, validation)."
|
|
42
|
+
},
|
|
43
|
+
{
|
|
44
|
+
"path": "docs/architecture/system-design/04-architecture-and-interfaces.md",
|
|
45
|
+
"required": false,
|
|
46
|
+
"when": "The system has more than one component, or integrates with outside services."
|
|
47
|
+
},
|
|
48
|
+
{
|
|
49
|
+
"path": "docs/architecture/system-design/05-execution-and-resilience.md",
|
|
50
|
+
"required": false,
|
|
51
|
+
"when": "Things run concurrently, in the background, or can fail part-way and need recovery."
|
|
52
|
+
},
|
|
53
|
+
{
|
|
54
|
+
"path": "docs/architecture/system-design/06-operations-and-scalability.md",
|
|
55
|
+
"required": false,
|
|
56
|
+
"when": "The team deploys, monitors or scales running services itself."
|
|
57
|
+
},
|
|
58
|
+
{
|
|
59
|
+
"path": "docs/architecture/system-design/07-ui-and-interaction-mapping.md",
|
|
60
|
+
"required": false,
|
|
61
|
+
"when": "User actions in an interface trigger system operations that change state."
|
|
62
|
+
},
|
|
63
|
+
{
|
|
64
|
+
"path": "docs/design/DESIGN.md",
|
|
65
|
+
"required": false,
|
|
66
|
+
"when": "The product has a visual or interactive interface."
|
|
67
|
+
},
|
|
68
|
+
{
|
|
69
|
+
"path": "docs/architecture/contracts/README.md",
|
|
70
|
+
"required": false,
|
|
71
|
+
"when": "An interface has several consumers, outside teams or versioning needs, so it needs a written contract."
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# Contracts (Optional)
|
|
2
|
+
|
|
3
|
+
Detailed API and event contracts — created only when the complexity justifies them: multiple consumers, versioning needs, or external teams. For simple interfaces, the summary in `04-architecture-and-interfaces.md` is enough.
|
|
4
|
+
|
|
5
|
+
- `api-<name>.md` — one per interface: operations, request and response shapes, errors, versioning and compatibility rules.
|
|
6
|
+
- `events-<stream>.md` — one per stream: event names, payloads, delivery guarantees and ordering.
|
|
7
|
+
|
|
8
|
+
Rules:
|
|
9
|
+
- Link every contract from `04-architecture-and-interfaces.md`.
|
|
10
|
+
- State compatibility expectations in the contract itself.
|
|
11
|
+
- Record breaking changes in an ADR.
|
package/template/profiles/core/templates/docs/architecture/system-design/01-system-overview.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# 1. System Overview
|
|
2
|
+
|
|
3
|
+
## Purpose
|
|
4
|
+
What is this system meant to achieve?
|
|
5
|
+
|
|
6
|
+
## Problem and context
|
|
7
|
+
What problem does it solve, and what situation is it running in?
|
|
8
|
+
|
|
9
|
+
## Actors and stakeholders
|
|
10
|
+
| Actor | Goals | Responsibilities |
|
|
11
|
+
|---|---|---|
|
|
12
|
+
| | | |
|
|
13
|
+
|
|
14
|
+
## Core capabilities
|
|
15
|
+
The main things the system does — described without picking an implementation.
|
|
16
|
+
|
|
17
|
+
## Scope and boundaries
|
|
18
|
+
What's inside the system, and what stays outside?
|
|
19
|
+
|
|
20
|
+
## External systems and dependencies
|
|
21
|
+
| System | Purpose | Relationship |
|
|
22
|
+
|---|---|---|
|
|
23
|
+
| | | |
|
|
24
|
+
|
|
25
|
+
## Constraints and assumptions
|
|
26
|
+
The business, technical, legal and operational limits that shape the design.
|
|
27
|
+
|
|
28
|
+
## Context diagram
|
|
29
|
+
Add one if it makes the actors and boundaries easier to see.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# 2. Domain & State Model
|
|
2
|
+
|
|
3
|
+
## Domain concepts
|
|
4
|
+
Agree on the important concepts, and use the same words for them everywhere.
|
|
5
|
+
|
|
6
|
+
## Entities and value objects
|
|
7
|
+
| Concept | Meaning | Identity / attributes |
|
|
8
|
+
|---|---|---|
|
|
9
|
+
| | | |
|
|
10
|
+
|
|
11
|
+
## Relationships
|
|
12
|
+
Describe who owns what, how things relate (one-to-many and so on — the cardinality), and how things are created, changed and retired.
|
|
13
|
+
|
|
14
|
+
## State model
|
|
15
|
+
What data does the system keep track of? For each piece, say who owns it and where the one copy that counts lives (the authoritative source).
|
|
16
|
+
|
|
17
|
+
## State transitions
|
|
18
|
+
How state moves from one value to another — the rules live in the behaviour document (`03-behaviour-and-business-rules.md`).
|
|
19
|
+
|
|
20
|
+
## Data structures and persistence
|
|
21
|
+
The shape of the data, how it's stored, how long it's kept, and how consistent it must be. Add detailed schemas separately only when they're genuinely useful.
|
|
22
|
+
|
|
23
|
+
## Modelling boundaries
|
|
24
|
+
Describe groupings such as aggregates or bounded contexts (DDD — Domain-Driven Design — vocabulary) only when they earn their place. DDD terms are optional.
|
|
25
|
+
|
|
26
|
+
## Glossary
|
|
27
|
+
Terms with precise meanings in this domain.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# 3. Behaviour & Business Rules
|
|
2
|
+
|
|
3
|
+
## Use cases and operations
|
|
4
|
+
| Operation | Actor | Intent | Result |
|
|
5
|
+
|---|---|---|---|
|
|
6
|
+
| | | | |
|
|
7
|
+
|
|
8
|
+
## Triggers and events
|
|
9
|
+
What starts things happening: user actions, schedules, outside events, or conditions inside the system?
|
|
10
|
+
|
|
11
|
+
## State transitions
|
|
12
|
+
| Current state | Trigger / command | Conditions | Next state | Side effects |
|
|
13
|
+
|---|---|---|---|---|
|
|
14
|
+
| | | | | |
|
|
15
|
+
|
|
16
|
+
## Business rules
|
|
17
|
+
The "always" and "never" statements the system must obey. The ID'd catalogue lives where requirements live: global rules in `docs/product/SPEC.md` (§7), feature rules in each feature spec. List here, by ID, the rules that shape the behaviour in this document.
|
|
18
|
+
|
|
19
|
+
## Invariants
|
|
20
|
+
What must always remain true — even when many things happen at once (concurrency) or part of the system fails.
|
|
21
|
+
|
|
22
|
+
## Validation and constraints
|
|
23
|
+
Which inputs are accepted, which are rejected, and where the hard limits are.
|
|
24
|
+
|
|
25
|
+
## Preconditions and postconditions
|
|
26
|
+
What must be true before an operation runs, and what's guaranteed to be true after it.
|
|
27
|
+
|
|
28
|
+
## Acceptance criteria
|
|
29
|
+
How we'll know it's done: link each behaviour to requirement IDs and tests.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# 4. Architecture & Interfaces
|
|
2
|
+
|
|
3
|
+
## Architectural approach
|
|
4
|
+
The overall style, and why it fits the requirements and constraints.
|
|
5
|
+
|
|
6
|
+
## Components and responsibilities
|
|
7
|
+
| Component | Responsibility | Owns state? | Depends on |
|
|
8
|
+
|---|---|---|---|
|
|
9
|
+
| | | | |
|
|
10
|
+
|
|
11
|
+
## Boundaries and dependency direction
|
|
12
|
+
Where trust, deployment and module boundaries sit, and which dependencies are allowed across them.
|
|
13
|
+
|
|
14
|
+
## Communication
|
|
15
|
+
How parts talk to each other: direct calls, queued messages, events, or shared storage.
|
|
16
|
+
|
|
17
|
+
## Interfaces and contracts
|
|
18
|
+
List the interfaces, who consumes them, their inputs and outputs, and how compatible they must stay. When a surface is substantial — multiple consumers, versioning needs, external teams — add a contract document under `docs/architecture/contracts/` and link it here.
|
|
19
|
+
|
|
20
|
+
## Integrations
|
|
21
|
+
External services: what data crosses, how you authenticate, and what you assume about them when they fail.
|
|
22
|
+
|
|
23
|
+
## Technology choices
|
|
24
|
+
Record the choices that matter; put the consequential ones in ADRs, together with the alternatives you rejected.
|
|
25
|
+
|
|
26
|
+
## Diagrams
|
|
27
|
+
Add component, sequence or deployment diagrams where they remove ambiguity.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 5. Execution & Resilience Model
|
|
2
|
+
|
|
3
|
+
## Runtime model
|
|
4
|
+
What actually runs: processes, services, clients, workers and jobs.
|
|
5
|
+
|
|
6
|
+
## Request and execution lifecycle
|
|
7
|
+
Walk through the important operations from trigger to completion.
|
|
8
|
+
|
|
9
|
+
## Concurrency model
|
|
10
|
+
Shared resources, race conditions, ordering needs, and how things are coordinated.
|
|
11
|
+
|
|
12
|
+
## Transactions and consistency
|
|
13
|
+
What must be atomic (all-or-nothing), and where "eventually consistent" (catching up after a delay) is acceptable.
|
|
14
|
+
|
|
15
|
+
## Background and asynchronous work
|
|
16
|
+
Queues, scheduled jobs, and what delivery guarantees they give — where applicable.
|
|
17
|
+
|
|
18
|
+
## Failure scenarios
|
|
19
|
+
| Failure | Effect | Detection | Response / recovery |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| | | | |
|
|
22
|
+
|
|
23
|
+
## Error handling
|
|
24
|
+
How errors are grouped, how they travel, and what the user or client actually sees.
|
|
25
|
+
|
|
26
|
+
## Retry, timeout and idempotency
|
|
27
|
+
Where retries are safe, how long to wait, and how duplicates are handled. An idempotent operation gives the same result whether it runs once or twice.
|
|
28
|
+
|
|
29
|
+
## Recovery
|
|
30
|
+
Compensation, replay, reconciliation, restoring from backup, or manual fixes — whatever applies.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
# 6. Operations & Scalability
|
|
2
|
+
|
|
3
|
+
## Operating model
|
|
4
|
+
Who runs the system day to day, and what are their routine jobs?
|
|
5
|
+
|
|
6
|
+
## Environments and deployment
|
|
7
|
+
The environments (dev, staging, production...), what gets released as a unit, and how configuration is handled.
|
|
8
|
+
|
|
9
|
+
## Observability
|
|
10
|
+
- Logs: structured fields, with sensitive data left out.
|
|
11
|
+
- Metrics: health, usage, latency, errors and business numbers.
|
|
12
|
+
- Traces: where following a request across components is worth it.
|
|
13
|
+
- Alerts: conditions worth acting on, how severe, and who owns them.
|
|
14
|
+
|
|
15
|
+
## Diagnostics and health
|
|
16
|
+
Health checks, readiness probes, debugging information and runbooks (step-by-step guides for handling incidents).
|
|
17
|
+
|
|
18
|
+
## Performance and capacity
|
|
19
|
+
| Workload | Expected load | Target / limit | Measurement |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| | | | |
|
|
22
|
+
|
|
23
|
+
## Scaling strategy
|
|
24
|
+
Where the bottlenecks will show up first, and the least complex way to scale that meets demand.
|
|
25
|
+
|
|
26
|
+
## Operational risks
|
|
27
|
+
Costs, vendor lock-in, maintenance burden, recovery time and capacity risks.
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
# 7. UI & Interaction Mapping
|
|
2
|
+
|
|
3
|
+
> For systems with no user interface, mark this not applicable and describe the API or operational interface instead.
|
|
4
|
+
>
|
|
5
|
+
> This document owns what the UI does to the system. How the interface looks, feels and is structured visually is owned by `docs/design/DESIGN.md`.
|
|
6
|
+
|
|
7
|
+
## Interfaces and user roles
|
|
8
|
+
The applications and channels, who uses each, and what they're allowed to do.
|
|
9
|
+
|
|
10
|
+
## Information architecture
|
|
11
|
+
How content is organised: navigation, major sections, and what goes together. The structure itself is owned by `docs/design/DESIGN.md` §7 — record here only what the system must serve (routes, supplied content).
|
|
12
|
+
|
|
13
|
+
## User journeys
|
|
14
|
+
Product-level journeys live in `docs/product/PRD.md`. Map here the important user goals from entry point to completion, as the system supports them.
|
|
15
|
+
|
|
16
|
+
## Screen / view inventory
|
|
17
|
+
Screens as system surfaces: what each shows and what can be done on it. Screen names, entry points and access are owned by `docs/design/DESIGN.md` §7.5 — use the same screen names in both.
|
|
18
|
+
|
|
19
|
+
| Screen or view | User goal | Data shown | Actions |
|
|
20
|
+
|---|---|---|---|
|
|
21
|
+
| | | | |
|
|
22
|
+
|
|
23
|
+
## Interaction-to-system mapping
|
|
24
|
+
| User interaction | System operation | State read / changed | Requirement |
|
|
25
|
+
|---|---|---|---|
|
|
26
|
+
| | | | |
|
|
27
|
+
|
|
28
|
+
## UI states
|
|
29
|
+
The states every screen can be in are owned by `docs/design/DESIGN.md` §6.4. Map each state to system behaviour: what the system returns or does in each case.
|
|
30
|
+
|
|
31
|
+
## Accessibility and interaction constraints
|
|
32
|
+
Standards (contrast, focus, input modes, responsive behaviour) are owned by `docs/design/DESIGN.md` §6.7. Record here the system-side constraints: what the system must support for keyboard, assistive technology, localisation and input.
|
|
33
|
+
|
|
34
|
+
## Design references
|
|
35
|
+
Link to prototypes, or to `docs/design/DESIGN.md` if one exists.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
# Design
|
|
2
|
+
|
|
3
|
+
> **No user interface? Skip this file.** For a product without screens — an API, a background service — mark this document not applicable and keep interface contracts in the architecture documents instead.
|
|
4
|
+
>
|
|
5
|
+
> **Start here.** Fill in these five sections first: §2 experience principles, §3.1 brand foundation, §4.3 semantic tokens, §5.3 component inventory, §6.4 UI states. The remaining sections can stay empty — fill them in when the work needs them.
|
|
6
|
+
>
|
|
7
|
+
> One document for everything about how the product looks, feels and is structured: identity, design tokens, components, UX and information architecture. Use it for anything with a visual or interactive interface. The system-facing side — which interaction triggers which system operation, and screens as system surfaces — is mapped in `docs/architecture/system-design/07-ui-and-interaction-mapping.md`. Use the same screen names and state lists in both.
|
|
8
|
+
|
|
9
|
+
## 1. Governance
|
|
10
|
+
|
|
11
|
+
- Design owner:
|
|
12
|
+
- Status:
|
|
13
|
+
- Supported platforms:
|
|
14
|
+
- Source of truth (design file / token package):
|
|
15
|
+
- Who reviews and approves changes:
|
|
16
|
+
|
|
17
|
+
How designs become code:
|
|
18
|
+
|
|
19
|
+
- Where tokens live and what formats they're exported to:
|
|
20
|
+
- Where components are implemented:
|
|
21
|
+
- Design review process:
|
|
22
|
+
- How visual regressions (unintended visual changes) are caught:
|
|
23
|
+
- How things get deprecated and migrated:
|
|
24
|
+
|
|
25
|
+
## 2. Product experience principles
|
|
26
|
+
|
|
27
|
+
A short list of principles to weigh trade-offs against. Keep them consistent with the brand attributes in §3.1.
|
|
28
|
+
|
|
29
|
+
## 3. Visual identity
|
|
30
|
+
|
|
31
|
+
Start with §3.1 (one of the first five). Fill §3.2–3.7 in when the work needs them.
|
|
32
|
+
|
|
33
|
+
### 3.1 Brand foundation
|
|
34
|
+
- Purpose:
|
|
35
|
+
- Mission:
|
|
36
|
+
- Audience:
|
|
37
|
+
- Positioning:
|
|
38
|
+
- Brand attributes:
|
|
39
|
+
- The feeling it should give people:
|
|
40
|
+
|
|
41
|
+
### 3.2 Logo system
|
|
42
|
+
- Primary mark:
|
|
43
|
+
- Alternate marks:
|
|
44
|
+
- Clear space:
|
|
45
|
+
- Minimum sizes:
|
|
46
|
+
- Approved backgrounds:
|
|
47
|
+
- Misuse to avoid:
|
|
48
|
+
|
|
49
|
+
### 3.3 Colour identity
|
|
50
|
+
The brand colours and where each may be used. Colours that mean something in the UI (like error red) belong in the token system (§4), not here.
|
|
51
|
+
|
|
52
|
+
### 3.4 Typography
|
|
53
|
+
- Typeface families and licensing:
|
|
54
|
+
- Weights:
|
|
55
|
+
- Hierarchy:
|
|
56
|
+
- Numerals / data display:
|
|
57
|
+
- Fallbacks:
|
|
58
|
+
|
|
59
|
+
### 3.5 Imagery and illustration
|
|
60
|
+
- Photography:
|
|
61
|
+
- Illustration:
|
|
62
|
+
- Iconography:
|
|
63
|
+
- Data visualization:
|
|
64
|
+
- Prohibited treatments:
|
|
65
|
+
|
|
66
|
+
### 3.6 Motion and sound identity
|
|
67
|
+
Include only where relevant. Motion timings and easings are tokens (§4.2); rules for using them live in §6.8.
|
|
68
|
+
|
|
69
|
+
### 3.7 Examples
|
|
70
|
+
Link to approved assets and examples. Never embed credentials or private asset links.
|
|
71
|
+
|
|
72
|
+
## 4. Design tokens
|
|
73
|
+
|
|
74
|
+
Start with §4.3 (one of the first five). Fill the other subsections in when needed.
|
|
75
|
+
|
|
76
|
+
Design tokens are the named values the UI is built from — colours, sizes, spacing and so on. Components should use these tokens, never one-off values.
|
|
77
|
+
|
|
78
|
+
### 4.1 Token principles
|
|
79
|
+
- Prefer semantic tokens in product components — a token named for its meaning, like `color.text.primary`, not a raw value.
|
|
80
|
+
- Keep raw palette values separate from the roles they play.
|
|
81
|
+
- Choose platform themes and modes deliberately.
|
|
82
|
+
- Avoid one-off values unless they're documented and justified.
|
|
83
|
+
- Keep the token source, generated outputs and design-tool values in sync.
|
|
84
|
+
|
|
85
|
+
### 4.2 Token categories
|
|
86
|
+
| Category | Examples |
|
|
87
|
+
|---|---|
|
|
88
|
+
| Colour | brand, text, surface, border, status |
|
|
89
|
+
| Typography | family, size, weight, line height, tracking |
|
|
90
|
+
| Spacing | inset, stack, inline, layout gap |
|
|
91
|
+
| Sizing | control height, icon size, container width |
|
|
92
|
+
| Shape | radius, border width |
|
|
93
|
+
| Elevation | shadow, overlay |
|
|
94
|
+
| Motion | duration, easing, distance |
|
|
95
|
+
| Breakpoints | compact, medium, expanded |
|
|
96
|
+
|
|
97
|
+
### 4.3 Semantic token catalogue
|
|
98
|
+
| Token | Meaning | Value / reference | Theme | Status |
|
|
99
|
+
|---|---|---|---|---|
|
|
100
|
+
| `color.text.primary` | Main readable text | [Value] | [Theme] | [Status] |
|
|
101
|
+
|
|
102
|
+
### 4.4 Naming convention
|
|
103
|
+
Pick a stable hierarchy, for example: `{category}.{role}.{variant}.{state}`
|
|
104
|
+
|
|
105
|
+
### 4.5 Themes and modes
|
|
106
|
+
Document light/dark, high-contrast, brand and platform modes where needed.
|
|
107
|
+
|
|
108
|
+
### 4.6 Token lifecycle
|
|
109
|
+
How tokens are proposed, reviewed, deprecated, migrated and removed.
|
|
110
|
+
|
|
111
|
+
### 4.7 Implementation source
|
|
112
|
+
- Canonical source:
|
|
113
|
+
- Generated formats:
|
|
114
|
+
- Package / file locations:
|
|
115
|
+
- Validation:
|
|
116
|
+
|
|
117
|
+
## 5. Components
|
|
118
|
+
|
|
119
|
+
Start with §5.3 (one of the first five). Fill the other subsections in when needed.
|
|
120
|
+
|
|
121
|
+
### 5.1 Component principles
|
|
122
|
+
How components are composed, reused, customised and owned.
|
|
123
|
+
|
|
124
|
+
### 5.2 Component specification template
|
|
125
|
+
|
|
126
|
+
For each component, fill in:
|
|
127
|
+
|
|
128
|
+
**[Component name]**
|
|
129
|
+
- Purpose:
|
|
130
|
+
- When to use:
|
|
131
|
+
- When not to use:
|
|
132
|
+
- Anatomy:
|
|
133
|
+
- Variants:
|
|
134
|
+
- Sizes:
|
|
135
|
+
- Properties / inputs:
|
|
136
|
+
- States: default, hover, focus, pressed, disabled, loading, error, selected
|
|
137
|
+
- Responsive behaviour:
|
|
138
|
+
- Accessibility:
|
|
139
|
+
- Content guidance:
|
|
140
|
+
- Examples:
|
|
141
|
+
- Implementation location:
|
|
142
|
+
- Tests:
|
|
143
|
+
|
|
144
|
+
### 5.3 Component inventory
|
|
145
|
+
| Component | Purpose | Status | Owner | Implementation |
|
|
146
|
+
|---|---|---|---|---|
|
|
147
|
+
|
|
148
|
+
### 5.4 Contribution rules
|
|
149
|
+
How components are reviewed, tested, documented, versioned and deprecated.
|
|
150
|
+
|
|
151
|
+
## 6. UX and interaction
|
|
152
|
+
|
|
153
|
+
Start with §6.4 (one of the first five). Fill the other subsections in when needed.
|
|
154
|
+
|
|
155
|
+
### 6.1 Navigation and wayfinding
|
|
156
|
+
### 6.2 Forms and validation
|
|
157
|
+
### 6.3 Search, filtering, and sorting
|
|
158
|
+
### 6.4 UI states (feedback and system status)
|
|
159
|
+
Cover loading, success, empty, error, offline, permission and destructive-action states. The system behaviour behind each state is mapped in `docs/architecture/system-design/07-ui-and-interaction-mapping.md`.
|
|
160
|
+
### 6.5 Error prevention and recovery
|
|
161
|
+
### 6.6 Content and microcopy
|
|
162
|
+
### 6.7 Accessibility and responsive behaviour
|
|
163
|
+
The standards to meet: supported input methods, text scaling, contrast, focus, keyboard and screen-reader behaviour, and how layouts adapt. System-side accessibility constraints are recorded in `docs/architecture/system-design/07-ui-and-interaction-mapping.md`.
|
|
164
|
+
### 6.8 Motion and reduced motion
|
|
165
|
+
How motion is used, and what replaces it when people turn it off. Durations, easings and distances come from the motion tokens (§4.2).
|
|
166
|
+
|
|
167
|
+
## 7. Information architecture
|
|
168
|
+
|
|
169
|
+
Fill this in when navigation or content structure is substantial. This section owns how content is organised and how screens relate (§7.5); `docs/architecture/system-design/07-ui-and-interaction-mapping.md` owns what each screen does to the system — use the same screen names in both.
|
|
170
|
+
|
|
171
|
+
### 7.1 Content and capability inventory
|
|
172
|
+
### 7.2 User groups and access needs
|
|
173
|
+
### 7.3 Navigation model
|
|
174
|
+
### 7.4 Hierarchy and taxonomy
|
|
175
|
+
### 7.5 Routes / screens / views
|
|
176
|
+
| ID | Name | Purpose | Entry points | Exit / next steps | Access |
|
|
177
|
+
|---|---|---|---|---|---|
|
|
178
|
+
### 7.6 Search and findability
|
|
179
|
+
### 7.7 Content lifecycle and ownership
|
|
180
|
+
|
|
181
|
+
## 8. Platform adaptations
|
|
182
|
+
|
|
183
|
+
Fill in when needed: where platform conventions differ, and what must stay consistent everywhere.
|
|
184
|
+
|
|
185
|
+
## 9. Research and validation
|
|
186
|
+
|
|
187
|
+
Fill in when needed: user research, usability testing, and how the information architecture is checked against real users (§7.1–7.7).
|
|
188
|
+
|
|
189
|
+
## 10. UX review checklist
|
|
190
|
+
|
|
191
|
+
Use this checklist when reviewing designs and implementations:
|
|
192
|
+
|
|
193
|
+
- [ ] Experience principles applied
|
|
194
|
+
- [ ] Navigation and wayfinding clear
|
|
195
|
+
- [ ] Forms follow the validation guidance (§6.2)
|
|
196
|
+
- [ ] Every system state covered (§6.4)
|
|
197
|
+
- [ ] Accessibility requirements met (§6.7)
|
|
198
|
+
- [ ] Responsive behaviour verified (§6.7)
|
|
199
|
+
- [ ] Motion respects reduced-motion preference (§6.8)
|
|
200
|
+
- [ ] Semantic tokens used — no one-off values (§4.1)
|
|
201
|
+
- [ ] Components match the specification template (§5.2)
|
|
202
|
+
- [ ] Content follows the microcopy guidance (§6.6)
|