# ATLAS — {{PROJECT_NAME}} project map

> **Purpose.** Graph index of the repo. Any sub-agent dropped into
> this directory reads this file *first* and follows hyperlinks to
> the specific file/section it needs — no grep, no glob, no wasted
> context. Every important module gets one entry; every entry has a
> *role* and a list of *talks-to* edges.
>
> **Pair-with.** Read [`.agents/skill/{{PROJECT_NAME}}/SKILL.md`](.agents/skill/{{PROJECT_NAME}}/SKILL.md)
> for the **error/pattern playbook** (what NOT to do, lessons paid
> for in production blood). ATLAS = *"where things live"*; SKILL =
> *"what to remember when you touch them"*.
>
> **Convention.** Delete sections that don't apply to this project,
> but keep the numbering for sections that remain so cross-project
> agents know where to look. See [ATLAS spec](https://github.com/Abbasi-Alain/atlas/blob/main/docs/SPEC.md).
>
> **Bootstrap.** Generated by `atlas init` on `{{DATE}}`. Update in
> the same commit as any structural change. SKILL §ATLAS-IS-INDEX.

---

## 0. Quick orientation

| You want to … | Start here |
|---|---|
| Run the project | [`README.md`](README.md) |
| Understand the architecture | §A1 below + [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) |
| Find why we decided X | §A3 ADR index |
| See what's planned | §A4 roadmap + [`TODO.md`](TODO.md) |
| Debug a known issue | [`.agents/skill/{{PROJECT_NAME}}/SKILL.md`](.agents/skill/{{PROJECT_NAME}}/SKILL.md) |
| Look up a domain term | §G Glossary |
| Find a service / port / queue | §R Runtime topology |
| Know what to watch when X fails | §O Observability |
| Run tests | §5 — smoke set in §5 footer |
| Prove a change works (done-gate) | §5 smoke/test command: `{{TEST_CMD}}` |
| Know when to hand up / escalate | [`SCARS.md`](SCARS.md) scarred cores + _(fill in: maintainer-only paths)_ |
| Build / deploy | §B |

---

## 1. Top-level files (repo root)

### 1.1 Code-relevant

| Node | Role | Talks-to |
|---|---|---|
| [`README.md`](README.md) | Public overview | — |
| [`{{PRIMARY_BUILD_FILE}}`](./{{PRIMARY_BUILD_FILE}}) | Build / deps config | §B |
| [`.agents/skill/{{PROJECT_NAME}}/SKILL.md`](.agents/skill/{{PROJECT_NAME}}/SKILL.md) | **Error + pattern playbook** | this file |

### 1.2 Project documents *(remove rows that don't exist)*

| Doc | Role |
|---|---|
| [`ARCHITECTURE.md`](ARCHITECTURE.md) | System architecture |
| [`DESIGN.md`](DESIGN.md) | Design rationale / decision log |
| [`docs/adr/`](docs/adr/) | **Architecture Decision Records** — immutable "why we chose X". See §A3. |
| [`ROADMAP.md`](ROADMAP.md) | Public-facing future direction |
| [`PLANS.md`](PLANS.md) | Internal plans |
| [`TODO.md`](TODO.md) | Open backlog |
| [`CHANGELOG.md`](CHANGELOG.md) | Release history |
| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to contribute |
| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | Community guidelines |
| [`SECURITY.md`](SECURITY.md) | Security policy + disclosure |
| [`docs/FAQ.md`](docs/FAQ.md) | Q&A — append substantive answers here (SKILL §MAINTAIN-DOCS) |
| [`docs/GUIDE.md`](docs/GUIDE.md) | User guide |
| [`docs/GLOSSARY.md`](docs/GLOSSARY.md) | Long-form glossary (§G is the short pointer table) |
| [`LICENSE`](LICENSE) | License |

---

## 2. Source — `{{SRC_DIR}}/`

### 2.1 Entry & wiring
_(fill in: CLI / server entry points, top-level package init)_

| Node | Role | Talks-to |
|---|---|---|
| _(file)_ | _(role)_ | _(other files this calls)_ |

### 2.2 Core domain logic
_(fill in)_

### 2.3 Data layer
_(fill in)_

### 2.4 Storage / persistence
_(fill in)_

### 2.5 _(rename me — project-specific subsystem)_
_(fill in)_

---

## 3. Service / runtime layer
_(if the project has long-running processes / web servers / workers; otherwise delete)_

### 3.1 IPC / message shapes
| Type | Producer | Consumer(s) |
|---|---|---|
| _(message type)_ | _(file)_ | _(file)_ |

---

## 4. Front-end / UI
_(if applicable; otherwise delete)_

> **Read order for UI work:** (1) shared util → (2) the specific
> component → (3) cache-bust bump. Then check SKILL §UI.

---

## 5. Tests — `tests/`

| Concern | Files |
|---|---|
| _(fill in)_ | _(fill in)_ |

**Smoke set** *(used after touching runtime / shared modules)*:
```
{{TEST_CMD}}
```
Should pass quickly (<30 s for the smoke subset).

---

## 6. Docs — `docs/`

See §1.2 above. Long-form docs that don't fit the universal table live here:

| File | Role |
|---|---|
| _(fill in others)_ | |

---

## 7. Cross-cutting concerns *(where they live)*

| Concern | Primary file | Secondary |
|---|---|---|
| Time zones / dates | _(file)_ | |
| Auth / sessions | _(file)_ | |
| Logging | _(file)_ | |
| Error handling | _(file)_ | |
| Caching | _(file)_ | |
| Concurrency / locks | _(file)_ | |
| Internationalisation | _(file)_ | |
| Feature flags | _(file)_ | |

---

## 8. Environment variables *(the ones that actually matter)*

| Var | Effect | Defined by |
|---|---|---|
| _(fill in)_ | | |

---

## 9. Edit-and-where rules of thumb

- **Add a new X** → which file to touch first, what test to add, what doc to update.
- _(fill in project-specific idioms)_

---

## A. Architecture references

> Pointers to deeper docs. Keep this section short — it's a router,
> not the content.

### A1. Architecture diagrams
| File | What it covers |
|---|---|
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | System diagram, request lifecycle |
| _(diagrams here)_ | |

### A2. Design rationale
| File | What it covers |
|---|---|
| [`DESIGN.md`](DESIGN.md) | Why this shape, trade-offs taken |

### A3. ADR index *(Architecture Decision Records)*

ADRs are **immutable**: once accepted, they never change — they get
*superseded* by newer ADRs that link back. This is the project's
canonical "why we did X" history. Every non-trivial decision should
become an ADR before it ships. Format: see [`docs/adr/0000-template.md`](docs/adr/0000-template.md).

| # | Title | Status | Date |
|---|---|---|---|
| 0001 | _(decision)_ | Accepted | _(date)_ |
| _(fill in)_ | | | |

### A4. Roadmap / plans
| File | Horizon |
|---|---|
| [`ROADMAP.md`](ROADMAP.md) | Public-facing direction |
| [`PLANS.md`](PLANS.md) | Internal plans |
| [`TODO.md`](TODO.md) | Open backlog |

---

## G. Glossary *(domain terms with project-specific meanings)*

> One-line per term. Agents read this so they don't re-derive what
> "envelope" or "tenant" or "lease" means *in this codebase*. For
> long definitions, point to `docs/GLOSSARY.md`.

| Term | Definition |
|---|---|
| _(term)_ | _(one-line definition)_ |

---

## D. Data model

> Entities, schemas, key relations. Point to migrations or schema
> files; don't duplicate them here.

### D1. Key entities
| Entity | Where defined | Notes |
|---|---|---|
| _(entity)_ | _(file)_ | _(invariants)_ |

### D2. Schemas / migrations
| Where | What |
|---|---|
| _(file/dir)_ | _(role)_ |

### D3. Persistence backends
| Backend | Used for | Connection config |
|---|---|---|
| _(e.g. Postgres)_ | _(tables)_ | _(env var / file)_ |

---

## X. External dependencies *(third-party — what agents CANNOT modify)*

| Dep | What it provides | Trust level | Where it's called |
|---|---|---|---|
| _(SDK / API)_ | _(role)_ | _(network / sandboxed)_ | _(file)_ |

---

## R. Runtime topology *(services, ports, queues, processes)*

| Component | Port / queue | Protocol | Talks-to |
|---|---|---|---|
| _(service)_ | _(:8080)_ | _(HTTP/WS)_ | _(other components)_ |

---

## O. Observability *(where to look when things go wrong)*

| Signal | Location | Notes |
|---|---|---|
| Application logs | _(path or service)_ | |
| Metrics | _(Prometheus / Datadog / file)_ | |
| Traces | _(Jaeger / Honeycomb / file)_ | |
| Error tracking | _(Sentry / file)_ | |
| Dashboards | _(URL or `dashboards/`)_ | |
| Alerts / oncall runbook | _(URL or `runbooks/`)_ | |

---

## Sec. Security boundaries

| Boundary | Where enforced | Notes |
|---|---|---|
| User auth | _(file)_ | _(method)_ |
| Service-to-service auth | _(file)_ | _(method)_ |
| Secret storage | _(env / vault / KMS)_ | _(rotation policy)_ |
| Untrusted input | _(file)_ | _(sanitisation)_ |
| PII handling | _(file)_ | _(retention)_ |

---

## B. Build & deploy

### B1. Local dev
```
# how to bootstrap a dev environment from a fresh clone
```

### B2. Build
```
# how to produce a release artifact
```

### B3. Test
See §5 above.

### B4. Deploy / release
| Environment | How to deploy | Owner |
|---|---|---|
| _(staging)_ | _(command / CI)_ | |
| _(production)_ | _(command / CI)_ | |

### B5. Rollback
_(one-line procedure)_

---

## Maintenance

This file is the **graph entry point**. If you add a top-level
module, change a service boundary, move files across sections, or
introduce a new external dependency — update this file **in the same
commit**. A stale ATLAS forces every future agent to re-grep the
tree. See SKILL §ATLAS-IS-INDEX.

To validate this file: `atlas check`. To enumerate every SKILL
anchor: `atlas anchors`.