📘 Handover Pack: Lead Developer

1. The "Living Documentation" Philosophy

"Code tells you what happens, Documentation tells you WHY it happens."

This documentation is not a static PDF to be filed away. It is an active part of the repository, versioned alongside the code.

• Location: docs/architecture/
• Source of Truth: The code is the truth for logic, this doc is the truth for intent and business rules.

2. Your Responsibilities

As the Lead Developer, you own the Architecture Decision Records (ADR).

1. When refactoring: Update the corresponding Module Analysis.
2. When changing rules: Update Specs/Current.
3. Code Reviews: Reject PRs that change business logic without a corresponding docs update.

3. High-Level Taxonomy

We have reorganized the documentation into a tree that mirrors cognitive load:

Folder	Purpose	Audience
overview/	The 10,000ft view. Domain Map & Landscape.	Everyone
specs/current/	The Law. How the system works right now.	Devs & POs
specs/proposals/	The Future. RFCs and drafts.	Architects
modules/	Deep technical analysis of the Monolith.	Senior Devs
analysis/	Metrics, Security & Volumetrics.	Management
guidelines/	The "Rules of Engagement" (Gherkin, Async).	Team

4. Key Strategic Decisions to Enforce

• Hybrid Specs: We don't use Use Cases for everything.
  • Use Gherkin for hidden backend rules (Calculations, Batches).
  • Use State Diagrams for Workflows (Refunds, Requests).
  • Use Use Cases ONLY for human-UI interactions.
  • Reference: guidelines/functional_strategy.md
• The "Anti-Headless" Stance: We are deliberately sticking to MVC for OrderMGT to leverage Kendo Grid features unless there is a specific ROI to move to React.
  • Reference: analysis/headless_migration_criticism.md

5. Maintenance Implementation

• Images: Stored in docs/architecture/images.
• Metadata: metadata.json tracks files for the AI Agent. Run python3 generator/organize_docs.py if you move files.
• PDF Generation: Use node generator/generate_pdf.js to create a snapshot for management.