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.