# Tamkeen Documentation Index

## Document Hierarchy

```
┌───────────────────────────────────────────────────────────┐
│  Level 1: Master Constitution                             │
│  Path: .specify/memory/constitution.md                    │
│  Any conflict with any other document → Constitution wins │
├───────────────────────────────────────────────────────────┤
│  Level 2: Constitution Files (HOW TO BUILD)               │
│  Path: CONSTITUTIONS/*.md                                 │
│  The EXCLUSIVE authority for implementation patterns      │
│  Any conflict with any other document → Constitution wins │
├───────────────────────────────────────────────────────────┤
│  Level 3: Specifications (WHAT TO BUILD)                  │
│  Path: SPECIFICATIONS/**/*.md                             │
│  Defines WHAT the system must be and its constraints      │
│  Any mention of HOW is a pointer, not a definition        │
├───────────────────────────────────────────────────────────┤
│  Level 4: This Index                                      │
│  Navigation hub — defines no rules                        │
└───────────────────────────────────────────────────────────┘
```

---

## Navigation by Question

### "Is this allowed?"

| Question | Go to |
|:---|:---|
| Can I delete a client or agent? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-001-1 |
| Can I modify a payment amount? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-004-4 |
| Can I use Repository or DTO without justification? | `CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` → Prohibitions |
| Can I write logic in Controller? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Controller Confinement |
| Can I use `float`? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-006-2 |
| Can I delete a signed contract? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-002-4 |
| Can I remove an investor flag? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-001-6 |
| Can I add shares for a non-investor client? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-005-9 |
| Can I create an investor without shares? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-001-8 |
| Can I delete a non-latest payment? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` → BR-004-6 |
| Can I put `__()` inside an Exception? | `CONSTITUTIONS/02_ERROR_BOUNDARIES.md` → Prohibitions |
| Can I create a ServiceProvider just to load Routes? | `CONSTITUTIONS/05_ROUTING_PROVIDERS.md` → Prohibitions |
| Can I put display functions (color/translation) inside an Enum? | `CONSTITUTIONS/03_ENUMS.md` → Prohibitions |
| Can I put business logic in Shared Domain? | `CONSTITUTIONS/06_SHARED_DOMAIN.md` → Belonging Litmus Test |
| Can I put a DB Query inside a Listener? | `CONSTITUTIONS/01_EVENTS_OBSERVERS.md` → Prohibitions |
| Can I add a semantic shortcut in ApiResponseFormatter? | `CONSTITUTIONS/02_ERROR_BOUNDARIES.md` → Formatting Layer Rules |
| Can I put a DB query inside a Resource? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Resource Prohibitions |
| Can I use `fromRequest()` inside a DTO? | `CONSTITUTIONS/09_DTOS.md` → Prohibitions |
| Can I put business validation in a FormRequest? | `CONSTITUTIONS/08_FORM_REQUESTS.md` → Delegation Map |
| Can I use `saveQuietly()` for flag updates? | `CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → NEVER |
| Can I hardcode language strings in responses? | `CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Security Mandates |

---

### "How do I build this?"

| Question | Go to |
|:---|:---|
| What is the system? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/01_VISION_AND_SCOPE.md` |
| What are the entities? | `SPECIFICATIONS/01_BUSINESS_CONTEXT/02_DOMAIN_MODEL.md` |
| How do I organize files? | `CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Project Structure |
| How do I write a Response? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Response Architecture |
| How do I handle Exceptions? | `CONSTITUTIONS/02_ERROR_BOUNDARIES.md` |
| How do I write a Model or Service? | `CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` |
| How do I write a Test? | `CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Testing Mandates |
| How do I translate a message? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Localization Confinement |
| How do I handle a file? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → File Handling Confinement |
| How do I write a Migration? | `CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` → Schema Conventions |
| How do I add a Route or Permission? | `CONSTITUTIONS/00_CONSTITUTION_INDEX.md` → Security Mandates |
| How do I build a complex response? | `CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` → Response Builders |
| When do I use an Enum? | `CONSTITUTIONS/03_ENUMS.md` |
| When do I use a DTO? | `CONSTITUTIONS/09_DTOS.md` → Decision Cheat Sheet |
| When do I use Scope vs Query Class vs Builder? | `CONSTITUTIONS/04_DATABASE_COMMUNICATION.md` → Decision Cheat Sheet |
| What is the Controller's role? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Controller Confinement |
| How do I write an Event and Listener? | `CONSTITUTIONS/01_EVENTS_OBSERVERS.md` |
| How do I build a Domain Exception? | `CONSTITUTIONS/02_ERROR_BOUNDARIES.md` → Section 3 |
| How do I build an Enum with behavior? | `CONSTITUTIONS/03_ENUMS.md` |
| How do I build a Write DTO? | `CONSTITUTIONS/09_DTOS.md` → Section 5 |
| How do I build a Sparse Update DTO? | `CONSTITUTIONS/09_DTOS.md` → Section 6 |
| How do I load Routes centrally? | `CONSTITUTIONS/05_ROUTING_PROVIDERS.md` |
| What is allowed in Shared? | `CONSTITUTIONS/06_SHARED_DOMAIN.md` |
| How do I write a Resource? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Resources |
| When do I use a Job vs Event? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Jobs Section |
| How do I write a Filter? | `CONSTITUTIONS/07_BOUNDARY_LAYERS.md` → Filters Section |
| What goes in FormRequest vs DTO vs Business Validator? | `CONSTITUTIONS/08_FORM_REQUESTS.md` → Delegation Map |

---

### "What are the specifications?"

| Question | Go to |
|:---|:---|
| Business rules | `SPECIFICATIONS/01_BUSINESS_CONTEXT/03_BUSINESS_RULES.md` |
| Functional requirements | `SPECIFICATIONS/02_REQUIREMENTS/01_FUNCTIONAL.md` |
| Performance and security requirements | `SPECIFICATIONS/02_REQUIREMENTS/02_NON_FUNCTIONAL.md` |
| Acceptance criteria | `SPECIFICATIONS/02_REQUIREMENTS/03_ACCEPTANCE_CRITERIA.md` |
| Endpoint specifications | `SPECIFICATIONS/06_API/06_0X_*.md` |
| Error codes | `SPECIFICATIONS/06_API/06_08_ERROR_CODES.md` |
| Terminology definitions | `SPECIFICATIONS/00_GLOSSARY.md` |

### "How does this work?"

| Question | Go to |
|:---|:---|
| How are roles inferred? | `SPECIFICATIONS/05_ALGORITHMS/01_ENTITY_INFERENCE.md` |
| How is math validated? | `SPECIFICATIONS/05_ALGORITHMS/02_CONTRACT_MATH_VALIDATION.md` |
| How does the payment engine work? | `SPECIFICATIONS/05_ALGORITHMS/03_PAYMENT_ENGINE.md` |
| How are dynamic fields calculated? | `SPECIFICATIONS/05_ALGORITHMS/04_COMPUTED_FIELDS.md` |
| How is narrative text generated? | `SPECIFICATIONS/05_ALGORITHMS/05_NARRATIVE_GENERATION.md` |
| Contract and installment states | `SPECIFICATIONS/03_ARCHITECTURE/02_STATE_MACHINES.md` |
| Why was this architectural decision made? | `SPECIFICATIONS/03_ARCHITECTURE/04_DECISION_RECORDS.md` |
| How does the MV work? | `SPECIFICATIONS/04_DATABASE/02_MATERIALIZED_VIEWS.md` |
| How does the performance strategy work? | `SPECIFICATIONS/03_ARCHITECTURE/03_PERFORMANCE_STRATEGY.md` |
| How is the contract detail response built? | `SPECIFICATIONS/06_API/06_04_CONTRACTS_ENDPOINTS.md` → GET /contracts/{id} |
| How is investor profit calculated? | `SPECIFICATIONS/05_ALGORITHMS/04_COMPUTED_FIELDS.md` → Sections 5.1, 5.7 |

### Database

| Question | Go to |
|:---|:---|
| Table schemas and columns | `SPECIFICATIONS/04_DATABASE/01_TABLES.md` |
| Materialized View SQL | `SPECIFICATIONS/04_DATABASE/02_MATERIALIZED_VIEWS.md` |
| Index definitions | `SPECIFICATIONS/04_DATABASE/03_INDEXES.md` |
| Relationships and ON DELETE rules | `SPECIFICATIONS/04_DATABASE/04_RELATIONSHIPS_AND_CONSTRAINTS.md` |

---

## Documentation Map

### 00 — Glossary

| File | Purpose |
|:-----|:--------|
| `00_GLOSSARY.md` | Precise definitions of domain and technical terms used across all documentation |

### 01 — Business Context

| File | Purpose |
|:-----|:--------|
| `01_VISION_AND_SCOPE.md` | What the system is and where its boundaries lie |
| `02_DOMAIN_MODEL.md` | Core entities, their characteristics, and conceptual relationships |
| `03_BUSINESS_RULES.md` | All business constraints (BR-001 through BR-007) — supreme authority for business logic |
| `04_BUSINESS_SCENARIOS.md` | Concrete examples demonstrating business rule application |

### 02 — Requirements

| File | Purpose |
|:-----|:--------|
| `01_FUNCTIONAL.md` | What the system must do (observable behavior) |
| `02_NON_FUNCTIONAL.md` | Quality attributes (performance, security, reliability) |
| `03_ACCEPTANCE_CRITERIA.md` | Testable completion criteria for each requirement |

### 03 — Architecture

| File | Purpose |
|:-----|:--------|
| `01_SYSTEM_OVERVIEW.md` | Technology stack and architectural patterns |
| `02_STATE_MACHINES.md` | Valid states and transitions for contracts and installments |
| `03_PERFORMANCE_STRATEGY.md` | Performance targets and high-level approaches |
| `04_DECISION_RECORDS.md` | "Why" behind system and data model choices |
| `04_DECISION_RECORDS_HISTORICAL.md` | Historical context for code structure decisions (rules migrated to CONSTITUTIONS/) |

### 04 — Database

| File | Purpose |
|:-----|:--------|
| `01_TABLES.md` | Schema for every table (columns, types, CHECK constraints) |
| `02_MATERIALIZED_VIEWS.md` | SQL definitions and output columns for all MVs |
| `03_INDEXES.md` | Every index with its purpose and usage examples |
| `04_RELATIONSHIPS_AND_CONSTRAINTS.md` | ON DELETE rules and conceptual relationship descriptions |

### 05 — Algorithms

| File | Purpose |
|:-----|:--------|
| `01_ENTITY_INFERENCE.md` | How roles are determined and when flags are assigned |
| `02_CONTRACT_MATH_VALIDATION.md` | Step-by-step mathematical validation |
| `03_PAYMENT_ENGINE.md` | Step-by-step logic for all payment operations |
| `04_COMPUTED_FIELDS.md` | Formulas for all dynamically calculated fields |
| `05_NARRATIVE_GENERATION.md` | Rules for self-contained audit narrative text |

### 06 — API

| File | Purpose |
|:-----|:--------|
| `06_01_AUTH_ENDPOINTS.md` | Login, logout, me, roles |
| `06_02_CUSTOMERS_ENDPOINTS.md` | Customer CRUD and list |
| `06_03_AGENTS_ENDPOINTS.md` | Agent CRUD |
| `06_04_CONTRACTS_ENDPOINTS.md` | Contract lifecycle and detail |
| `06_05_PAYMENTS_ENDPOINTS.md` | Payment recording, modification, deletion |
| `06_06_ANALYTICS_ENDPOINTS.md` | Summary and investor analytics |
| `06_07_NOTIFICATIONS_ENDPOINTS.md` | Template CRUD and text generation |
| `06_08_ERROR_CODES.md` | Canonical catalog of all error scenarios and translation keys |
| `06_09_SHARES_ENDPOINTS.md` | Shares add/withdraw/modify/delete/log |
| `06_10_INVESTORS_ENDPOINTS.md` | Investor creation, list, detail, update |

### 07 — Constitutions (How to Build)

| File | Purpose |
|:---|:--------|
| `00_CONSTITUTION_INDEX.md` | Authority hierarchy, cross-cutting mandates, navigation |
| `01_EVENTS_OBSERVERS.md` | When do I use Event/Listener/Observer? |
| `02_ERROR_BOUNDARIES.md` | How do I build an Exception and map it to HTTP? |
| `03_ENUMS.md` | What is allowed inside an Enum? What goes to Display Class? |
| `04_DATABASE_COMMUNICATION.md` | When to use Scope vs Query Class vs Builder? When to use DTO? |
| `05_ROUTING_PROVIDERS.md` | How are routes loaded centrally? When to create ServiceProvider? |
| `06_SHARED_DOMAIN.md` | What is allowed in Shared? What is prohibited? |
| `07_BOUNDARY_LAYERS.md` | What are the rules for Resource, Job, Filter, Controller? |
| `08_FORM_REQUESTS.md` | What belongs in FormRequest only? What goes to DTO or Business Validator? |
| `09_DTOS.md` | What are the three DTO types? When to use each? |

---

## Specs Roadmap

```
Phase 1: Foundation     → SP-01 (Auth) → SP-02 (DB) → SP-03 (Architecture)
Phase 2: Core Domain   → SP-04 (Customer) → SP-05 (Agent)
Phase 3: Engine        → SP-06 (Calculator) → SP-07 (Contract) → SP-08 (Payment)
Phase 4: Intelligence  → SP-09 (Listing, merged into SP-04) → SP-10 (Analytics) → SP-11 (Notifications)
Phase 5: Investors     → SP-12 (Shares Domain) → SP-13 (Investor Domain)