Architecture

Architecture

Tools for documenting and visualizing software architecture.

Mermaid diagrams

Generate Mermaid diagram syntax for rendering in Markdown or docs.

Sequence diagram

sequenceDiagram
    participant Client
    participant API
    participant DB
    Client->>API: POST /login
    API->>DB: SELECT user
    DB-->>API: user record
    API-->>Client: 200 JWT token

Architecture diagram (flowchart)

flowchart TD
    LB[Load Balancer] --> API1[API Server 1]
    LB --> API2[API Server 2]
    API1 --> DB[(PostgreSQL)]
    API2 --> DB
    API1 --> Cache[(Redis)]
    API2 --> Cache
    API1 --> Queue[SQS Queue]
    Queue --> Worker[Worker Service]
    Worker --> DB

Entity relationship diagram

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"
    USER {
        string id PK
        string email
        string name
    }
    ORDER {
        string id PK
        string userId FK
        datetime createdAt
    }

C4 Context (using flowchart)

flowchart TD
    User[fa:fa-user User] -->|Uses| WebApp[Web Application]
    WebApp -->|API calls| Backend[Backend Service]
    Backend -->|Reads/Writes| DB[(Database)]
    Backend -->|Sends| Email[Email Service]
    Backend -->|Publishes| Queue[Message Queue]

Architecture Decision Records (ADR)

Write ADRs to docs/adr/ using the standard template:

mkdir -p docs/adr
cat > docs/adr/0001-use-postgresql.md << 'EOF'
# 1. Use PostgreSQL as Primary Database

Date: $(date +%Y-%m-%d)

## Status

Accepted

## Context

We need a relational database for our application data.

## Decision

We will use PostgreSQL as our primary database.

## Consequences

- Strong SQL support and JSON capabilities
- Well-supported by our ORM (Prisma/TypeORM)
- Requires operational knowledge for maintenance
EOF

List ADRs

ls -1 docs/adr/*.md 2>/dev/null | while read f; do head -1 "$f" | sed 's/^# //'; done

PlantUML (text-based)

@startuml
actor User
participant "Web App" as Web
participant "API" as API
database "DB" as DB

User -> Web : Login
Web -> API : POST /auth
API -> DB : Query user
DB --> API : User data
API --> Web : JWT
Web --> User : Dashboard
@enduml

Dependency graph (from package.json)

python3 -c "
import json, sys
pkg = json.load(open('package.json'))
deps = pkg.get('dependencies', {})
name = pkg.get('name', 'app')
lines = ['flowchart LR']
for dep in sorted(deps):
    lines.append(f'    {name} --> {dep}')
print('\n'.join(lines))
"

Notes

• Mermaid renders natively in GitHub Markdown (use ```mermaid code blocks).
• ADRs should be numbered sequentially and never deleted (supersede instead).
• Keep diagrams in version control alongside code.
• Use C4 model levels: Context → Container → Component → Code.