961tech docs¶
Internal documentation for 961tech — a multi-retailer PC parts price comparison and compatibility-checked builder for Lebanon.
How this site is organised¶
This is a docs-as-code site. The source lives at Amine32/961tech under docs/, builds with MkDocs Material, and deploys on every push to master. Edit a page on disk, push, and the site updates.
Every doc belongs to one of these artifact types. Pick the right type for what you're writing — that's how things stay findable months from now.
| Type | What it is | When you write one |
|---|---|---|
| Guides | Tutorials and walkthroughs (read once, then move on) | Onboarding-style content, end-to-end how-to (e.g., adding a scraper). |
| Architecture | Living description of the system as it exists today | After a structural change. The current state, not the history. |
| ADR — Architecture Decision Record | Why we chose X over Y, frozen at decision time | Whenever a non-trivial decision locks in (data model, library, deployment shape, protocol). Numbered, append-only. |
| RFC — Request for Comments | Proposal for a major feature or change, debated before implementation | Before building anything that touches more than one module or has a non-obvious design. |
| Spec | Frozen feature design at build time | Once a feature is greenlit. Captures the agreed shape; not updated after. |
| Plan | Implementation plan for a phase or ticket | When breaking down work that spans multiple sessions. |
| Runbook | Operational how-to | Whenever a procedure has more than three steps and could be done by someone other than you. |
| Reference | API contracts, data models, env vars | The canonical place to look up "what fields does Listing have." |
| Postmortem | What went wrong + what we changed | After any incident or rejected piece of work. |
| Principles | Engineering values + anti-patterns | Single living doc — the why above the ADRs. |
| Design system | Colors, fonts, spacing, components | Single living doc. Not a directory. |
| Glossary | Domain terms | Single living doc. Not a directory. |
Conventions¶
For a full conventions sheet (file naming, frontmatter, review checklist), see Contributing.
The shorthand:
- Naming. ADRs and RFCs are numbered (
0001-...). Specs, plans, postmortems are dated (YYYY-MM-DD-...). Runbooks, guides, reference, architecture pages are slug-named. Templates start with_and aren't published. - Status. Every page declares its status in frontmatter:
new,stub,active,frozen, ordeprecated. - Diagrams. Mermaid by default. drawio only when mermaid can't express what you need.
For Claude instances picking up work¶
Read /CLAUDE.md at the repo root first — it's the operational onboarding.
Then come back here for the architectural context, and to Guides → Doing your first ticket for the workflow.