113 lines
3.9 KiB
Markdown
113 lines
3.9 KiB
Markdown
# Contract: Project Bible (bible-local/)
|
|
|
|
Version: 1.0
|
|
|
|
## Purpose
|
|
|
|
`bible-local/` is the single source of truth for everything **specific to this project**:
|
|
data model, API surface, business rules, architectural decisions.
|
|
|
|
Shared engineering rules (CSV, logging, DB, tables, etc.) live in the `bible/` submodule.
|
|
Do not duplicate them in `bible-local/`.
|
|
|
|
## Required Files
|
|
|
|
Every project bible must have these files:
|
|
|
|
```
|
|
bible-local/
|
|
README.md — index: what files exist and what each covers
|
|
architecture/
|
|
system-overview.md — what the product does, active scope, non-goals
|
|
data-model.md — domain entities, DB tables, naming conventions
|
|
api-surface.md — all HTTP endpoints with methods and response shape
|
|
runtime-flows.md — key mutation flows, invariants, critical rules
|
|
decisions/
|
|
README.md — ADL format explanation
|
|
YYYY-MM-DD-topic.md — one file per architectural decision
|
|
```
|
|
|
|
Optional (add when relevant):
|
|
```
|
|
architecture/
|
|
ui-information-architecture.md — page structure, navigation, UI invariants
|
|
docs/
|
|
INTEGRATION_GUIDE.md — external system integration (formats, protocols)
|
|
```
|
|
|
|
## system-overview.md Rules
|
|
|
|
- List what is **in scope** and what is **explicitly out of scope**.
|
|
- Out of scope section prevents scope creep — update it when you reject a feature.
|
|
- Include tech stack and local run command.
|
|
|
|
## data-model.md Rules
|
|
|
|
- Document canonical naming: if domain model uses `Machine` but API uses `asset`, say so explicitly.
|
|
- List all DB tables with one-line description of each.
|
|
- Document any non-obvious invariants (e.g. "parts are projections of history, not source of truth").
|
|
- Migration policy: how migrations are numbered and applied.
|
|
|
|
## api-surface.md Rules
|
|
|
|
- Every endpoint: method, path, brief description, key response fields.
|
|
- Group by domain area (Registry, Ingest, Timeline, etc.).
|
|
- Note any endpoints that are UI-only routes vs JSON API.
|
|
- Document pagination, filtering params where non-obvious.
|
|
|
|
## runtime-flows.md Rules
|
|
|
|
This is the most important file. Document flows that are **easy to break**:
|
|
|
|
- Mutation paths (what happens step by step when user does X)
|
|
- Event/time source priority rules
|
|
- Deduplication logic
|
|
- Cross-entity side effects (e.g. removing a component affects asset status)
|
|
- Anything that caused a bug or regression — add a "DO NOT reintroduce" note
|
|
|
|
Format each flow as a numbered list of steps, not prose.
|
|
|
|
## Architectural Decision Log (ADL)
|
|
|
|
Write a decision entry when:
|
|
- You choose between two non-obvious approaches
|
|
- You intentionally reject a feature or pattern
|
|
- A bug caused a rule change (e.g. cursor safety)
|
|
- You freeze or deprecate something
|
|
|
|
**Format:**
|
|
|
|
```markdown
|
|
# Decision: <short title>
|
|
|
|
**Date:** YYYY-MM-DD
|
|
**Status:** active | superseded by YYYY-MM-DD-topic.md
|
|
|
|
## Context
|
|
What situation made this decision necessary.
|
|
|
|
## Decision
|
|
What was decided, stated clearly.
|
|
|
|
## Consequences
|
|
What this means going forward. What is now forbidden or required.
|
|
```
|
|
|
|
- One decision per file, named `YYYY-MM-DD-short-topic.md`.
|
|
- When a decision is superseded, add `superseded by` to the old file's status — do not delete it.
|
|
- Record the decision **in the same commit** as the code that implements it.
|
|
|
|
## What NOT to Put in bible-local/
|
|
|
|
- Generic rules (CSV format, logging, pagination) → these are in `bible/rules/patterns/`
|
|
- Work-in-progress notes, TODO lists → use issues or a separate `docs/` folder
|
|
- Duplicate of what is already in code (don't restate what the code clearly shows)
|
|
- Speculative future architecture — document what exists, not what might exist
|
|
|
|
## Keeping the Bible Current
|
|
|
|
- Update `bible-local/` in the **same commit** as the code change it describes.
|
|
- If you change a flow, update `runtime-flows.md` in the same PR.
|
|
- If a section becomes outdated, fix or delete it — stale docs are worse than no docs.
|
|
- Bible files are in **English only**.
|