Architecture

Name: architecture
Rating: 87
Author: ThinkfleetAI

Tools for documenting and visualizing software architecture.

Mermaid diagrams

Generate Mermaid diagram syntax for rendering in Markdown or docs.

Sequence diagram

code

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)

code

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

code

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)

code

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:

bash

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

bash

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

PlantUML (text-based)

code

@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)

bash

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.