mirror of
https://github.com/azaion/admin.git
synced 2026-04-22 22:56:32 +00:00
Oleksandr Bezdieniezhnykh
129 lines
3.5 KiB
Markdown
129 lines
3.5 KiB
Markdown
# Architecture Document Template
|
|
|
|
Use this template for the architecture document. Save as `_docs/02_document/architecture.md`.
|
|
|
|
---
|
|
|
|
```markdown
|
|
# [System Name] — Architecture
|
|
|
|
## 1. System Context
|
|
|
|
**Problem being solved**: [One paragraph summarizing the problem from problem.md]
|
|
|
|
**System boundaries**: [What is inside the system vs. external]
|
|
|
|
**External systems**:
|
|
|
|
| System | Integration Type | Direction | Purpose |
|
|
|--------|-----------------|-----------|---------|
|
|
| [name] | REST / Queue / DB / File | Inbound / Outbound / Both | [why] |
|
|
|
|
## 2. Technology Stack
|
|
|
|
| Layer | Technology | Version | Rationale |
|
|
|-------|-----------|---------|-----------|
|
|
| Language | | | |
|
|
| Framework | | | |
|
|
| Database | | | |
|
|
| Cache | | | |
|
|
| Message Queue | | | |
|
|
| Hosting | | | |
|
|
| CI/CD | | | |
|
|
|
|
**Key constraints from restrictions.md**:
|
|
- [Constraint 1 and how it affects technology choices]
|
|
- [Constraint 2]
|
|
|
|
## 3. Deployment Model
|
|
|
|
**Environments**: Development, Staging, Production
|
|
|
|
**Infrastructure**:
|
|
- [Cloud provider / On-prem / Hybrid]
|
|
- [Container orchestration if applicable]
|
|
- [Scaling strategy: horizontal / vertical / auto]
|
|
|
|
**Environment-specific configuration**:
|
|
|
|
| Config | Development | Production |
|
|
|--------|-------------|------------|
|
|
| Database | [local/docker] | [managed service] |
|
|
| Secrets | [.env file] | [secret manager] |
|
|
| Logging | [console] | [centralized] |
|
|
|
|
## 4. Data Model Overview
|
|
|
|
> High-level data model covering the entire system. Detailed per-component models go in component specs.
|
|
|
|
**Core entities**:
|
|
|
|
| Entity | Description | Owned By Component |
|
|
|--------|-------------|--------------------|
|
|
| [entity] | [what it represents] | [component ##] |
|
|
|
|
**Key relationships**:
|
|
- [Entity A] → [Entity B]: [relationship description]
|
|
|
|
**Data flow summary**:
|
|
- [Source] → [Transform] → [Destination]: [what data and why]
|
|
|
|
## 5. Integration Points
|
|
|
|
### Internal Communication
|
|
|
|
| From | To | Protocol | Pattern | Notes |
|
|
|------|----|----------|---------|-------|
|
|
| [component] | [component] | Sync REST / Async Queue / Direct call | Request-Response / Event / Command | |
|
|
|
|
### External Integrations
|
|
|
|
| External System | Protocol | Auth | Rate Limits | Failure Mode |
|
|
|----------------|----------|------|-------------|--------------|
|
|
| [system] | [REST/gRPC/etc] | [API key/OAuth/etc] | [limits] | [retry/circuit breaker/fallback] |
|
|
|
|
## 6. Non-Functional Requirements
|
|
|
|
| Requirement | Target | Measurement | Priority |
|
|
|------------|--------|-------------|----------|
|
|
| Availability | [e.g., 99.9%] | [how measured] | High/Medium/Low |
|
|
| Latency (p95) | [e.g., <200ms] | [endpoint/operation] | |
|
|
| Throughput | [e.g., 1000 req/s] | [peak/sustained] | |
|
|
| Data retention | [e.g., 90 days] | [which data] | |
|
|
| Recovery (RPO/RTO) | [e.g., RPO 1hr, RTO 4hr] | | |
|
|
| Scalability | [e.g., 10x current load] | [timeline] | |
|
|
|
|
## 7. Security Architecture
|
|
|
|
**Authentication**: [mechanism — JWT / session / API key]
|
|
|
|
**Authorization**: [RBAC / ABAC / per-resource]
|
|
|
|
**Data protection**:
|
|
- At rest: [encryption method]
|
|
- In transit: [TLS version]
|
|
- Secrets management: [tool/approach]
|
|
|
|
**Audit logging**: [what is logged, where, retention]
|
|
|
|
## 8. Key Architectural Decisions
|
|
|
|
Record significant decisions that shaped the architecture.
|
|
|
|
### ADR-001: [Decision Title]
|
|
|
|
**Context**: [Why this decision was needed]
|
|
|
|
**Decision**: [What was decided]
|
|
|
|
**Alternatives considered**:
|
|
1. [Alternative 1] — rejected because [reason]
|
|
2. [Alternative 2] — rejected because [reason]
|
|
|
|
**Consequences**: [Trade-offs accepted]
|
|
|
|
### ADR-002: [Decision Title]
|
|
|
|
...
|
|
```
|