ADR ও Documentation

কেন ADR?

"কেন এই সিদ্ধান্ত?" — 6 মাস পরে সবাই ভুলে যায়। ADR context, options, consequence লিখে রাখে।

ADR Format (Michael Nygard)

# ADR 0007: Use PostgreSQL

## Status
Accepted (2024-03-15)

## Context
Multi-tenant SaaS, JSON columns ও complex query দরকার।

## Decision
PostgreSQL 15 ব্যবহার।

## Consequences
✅ Strong jsonb, full-text, mature
❌ Team-এর MySQL experience বেশি

## Alternatives
- MySQL: weaker JSON
- MongoDB: transaction limited

ADR Tools

• adr-tools CLI
• Markdown in docs/adr/
• Number: 0001, 0002
• Status: Proposed → Accepted → Superseded

C4 Model — Simon Brown ⭐

L1 System Context

[User] [Admin]
   ↓      ↓
[E-commerce System]
   ↓      ↓
[Bank] [Email]

L2 Container

[SPA React] ↔ [API .NET] ↔ [PG DB]
                  ↓
              [Redis]

L3 Component

Container-এর ভিতরের components।

L4 Code

UML class diagram।

Tools

Structurizr, PlantUML, Mermaid, Draw.io।

HLD vs LLD

HLD	LLD
System overview	Component detail
Module interaction	Class, method, schema
Architect	Senior dev

HLD Sections

1. Overview, 2. Goals
3. Architecture (C4 L2)
4. Tech Stack, 5. Data Flow
6. APIs, 7. Security
8. Scalability, 9. Deployment
10. Risks & Trade-offs

LLD Sections

Class diagrams, sequence diagrams, ER, API contracts (OpenAPI), state machines, test cases।

Docs-as-Code ⭐

repo/
├── docs/
│   ├── architecture/
│   │   ├── overview.md
│   │   └── adr/
│   ├── api/        # OpenAPI
│   ├── runbooks/
│   └── onboarding.md
└── mkdocs.yml

Tools

MkDocs+Material, Docusaurus, GitBook, ReadTheDocs।

Diátaxis Framework

1. Tutorials — শেখানো
2. How-to Guides — task
3. Reference — API detail
4. Explanation — concept