Create Architecture Documentation

Task

Analyse the codebase and create comprehensive architecture documentation at /docs/docs/llm/architecture.md.

Steps

1. Understand the system:
2. Read all code, documentation, and configuration files
3. Identify all services, databases, and external integrations
4. Understand deployment structure (Docker Compose, containers, networks)

5. Map data flow between components

6. Document architectural decisions:

7. System components and their responsibilities
8. Database strategy (why multiple databases, what each stores)
9. Service communication patterns (networks, protocols, security)
10. File storage strategy and rationale
11. Authentication and authorisation architecture
12. Integration patterns (FHIR, OpenEHR, object storage)

13. Key design patterns in use

14. Include strategic context:

15. Technology choices and justifications
16. Why this architecture vs. alternatives
17. Scalability considerations and migration paths
18. Security boundaries and isolation strategies
19. Performance characteristics

20. Backup and disaster recovery approach

21. Avoid hallucination - verify with human:

22. Document ONLY the architecture that exists in docker-compose files, code, and documentation
23. Do not invent services, databases, or integrations that don't exist
24. Do not assume future architecture without evidence in roadmap/docs
25. If architectural decisions aren't clear, flag: ❓ CLARIFY: [question]
26. When you must infer architectural rationale, state: 🔍 ASSUMPTION: [what you're assuming]
27. If architecture seems incomplete or inconsistent, mark: ⚠️ INCOMPLETE: [what's unclear]

Output Format

Structure as:

• System Overview: High-level description with component diagram
• Service Architecture: Each service's role, technology, and responsibilities
• Database Strategy: Why separated, what each stores, access patterns
• Storage Architecture: File storage approach and rationale
• Network Architecture: Service communication, security boundaries
• Integration Patterns: How services interact (FHIR, OpenEHR, APIs)
• Security Architecture: Authentication, authorisation, data protection
• Scalability & Migration: Current limits, growth paths, future plans
• Key Architectural Decisions: Major choices and their justifications
• Questions for Human: List all ❓ CLARIFY items
• Assumptions to Verify: List all 🔍 ASSUMPTION items
• Architectural Gaps: List all ⚠️ INCOMPLETE items

Ask for clarification in chat

• After you have completed the above, via a numbered list, ask the user to clarify CLARIFY, ASSUMPTION and INCOMPLETE items, in the chat.