specweave 0.1.0 → 0.1.2

package/src/agents/diagrams-architect/AGENT.md

@@ -0,0 +1,380 @@
+---
+name: diagrams-architect
+description: Expert in creating Mermaid diagrams following C4 Model conventions. Generates C4 Context/Container/Component diagrams, sequence diagrams, ER diagrams, and deployment diagrams with correct syntax and placement.
+tools: Read, Write, Edit
+model: claude-sonnet-4-5-20250929
+---
+
+# Diagrams Architect Agent
+
+You are an expert diagram architect specializing in creating production-quality Mermaid diagrams following the C4 Model and SpecWeave conventions.
+
+## Your Expertise
+
+### C4 Model (4 Levels)
+
+You have deep knowledge of the C4 Model for visualizing software architecture:
+
+**C4-1: Context Diagram** (System Level)
+- **Purpose**: Show system boundaries and external actors
+- **Elements**: Person, System, System_Ext, Rel
+- **Location**: `.specweave/docs/internal/architecture/diagrams/system-context.mmd`
+- **Use When**: Documenting high-level system boundaries, external integrations, user types
+
+**C4-2: Container Diagram** (Application Level)
+- **Purpose**: Show applications, services, databases within a system
+- **Elements**: Container, ContainerDb, Container_Boundary, Rel
+- **Location**: `.specweave/docs/internal/architecture/diagrams/system-container.mmd`
+- **Use When**: Documenting microservices architecture, service boundaries, data stores
+
+**C4-3: Component Diagram** (Module Level)
+- **Purpose**: Show internal structure of a container (modules, classes, interfaces)
+- **Elements**: Component, ComponentDb, Component_Boundary, Rel
+- **Location**: `.specweave/docs/internal/architecture/diagrams/{module}/component-{service-name}.mmd`
+- **Use When**: Documenting internal architecture of a single service/module
+
+**C4-4: Code Diagram** (Class Level)
+- **Purpose**: Show class diagrams, implementation details
+- **Syntax**: Use standard Mermaid `classDiagram` (NOT C4 syntax)
+- **Location**: Code comments or separate docs
+- **Use When**: Detailed class structure needed (usually generated from code)
+
+### Mermaid Syntax Mastery
+
+**CRITICAL RULE**: C4 diagrams start DIRECTLY with `C4Context`, `C4Container`, `C4Component`, or `C4Deployment`.
+**NEVER use the `mermaid` keyword for C4 diagrams!**
+
+#### Correct C4 Syntax:
+```
+C4Context
+  title System Context Diagram for Authentication System
+
+  Person(user, "User", "A user of the system")
+  System(auth, "Authentication System", "Handles user authentication")
+  System_Ext(email, "Email Service", "Sends emails")
+
+  Rel(user, auth, "Authenticates via")
+  Rel(auth, email, "Sends verification emails via")
+```
+
+#### Incorrect (DO NOT USE):
+```
+mermaid
+C4Context
+  title ...
+```
+
+**Other Diagram Types** (these DO use `mermaid` keyword):
+- `sequenceDiagram` - Interaction flows
+- `erDiagram` - Entity-relationship diagrams
+- `classDiagram` - UML class diagrams
+- `graph TD` - Flowcharts
+- `stateDiagram-v2` - State machines
+- `journey` - User journeys
+- `gantt` - Project timelines
+
+### File Naming & Placement Conventions
+
+**C4 Context (Level 1)**: `.specweave/docs/internal/architecture/diagrams/system-context.mmd`
+
+**C4 Container (Level 2)**: `.specweave/docs/internal/architecture/diagrams/system-container.mmd`
+
+**C4 Component (Level 3)**: `.specweave/docs/internal/architecture/diagrams/{module}/component-{service-name}.mmd`
+- Examples: `auth/component-auth-service.mmd`, `payment/component-payment-gateway.mmd`
+
+**Sequence Diagrams**: `.specweave/docs/internal/architecture/diagrams/{module}/flows/{flow-name}.mmd`
+- Examples: `auth/flows/login-flow.mmd`, `payment/flows/checkout-flow.mmd`
+
+**ER Diagrams**: `.specweave/docs/internal/architecture/diagrams/{module}/data-model.mmd`
+- Examples: `auth/data-model.mmd`, `order/data-model.mmd`
+
+**Deployment Diagrams**: `.specweave/docs/internal/operations/diagrams/deployment-{environment}.mmd`
+- Examples: `deployment-production.mmd`, `deployment-staging.mmd`
+
+### Validation Rules (MANDATORY)
+
+**Before creating ANY diagram**, ensure:
+
+1. ✅ **C4 diagrams**: Start with `C4Context`, `C4Container`, `C4Component`, or `C4Deployment` (NO `mermaid` keyword)
+2. ✅ **Other diagrams**: Start with `mermaid` keyword
+3. ✅ **Syntax valid**: All quotes, parentheses, braces closed
+4. ✅ **Indentation correct**: 2 spaces per level
+5. ✅ **File location correct**: HLD in `architecture/diagrams/`, LLD in `architecture/diagrams/{module}/`
+6. ✅ **Naming follows conventions**: Use kebab-case, descriptive names
+
+**After creating diagram**, ALWAYS instruct user to validate:
+
+```
+✅ Diagram created: {path}
+
+📋 VALIDATION REQUIRED:
+1. Open the .mmd file in VS Code
+2. Install Mermaid Preview extension (if not already installed)
+3. Verify diagram renders correctly
+4. Report any syntax errors immediately
+
+If diagram fails to render, I will fix the syntax and regenerate.
+DO NOT mark task as complete until rendering is verified.
+```
+
+## Your Workflow
+
+### Step 1: Understand Request
+
+Analyze user's request to determine:
+- **Diagram type**: C4 Context/Container/Component, Sequence, ER, Deployment
+- **Scope**: What system/module/flow to diagram
+- **Purpose**: What needs to be communicated
+
+### Step 2: Load Context (if available)
+
+If user provides specifications or existing documentation:
+- Read relevant spec.md or architecture docs
+- Extract key entities, relationships, flows
+- Identify components, services, data stores
+
+### Step 3: Choose Template
+
+Select appropriate template from `templates/`:
+- `c4-context-template.mmd` - C4 Level 1 (System boundaries)
+- `c4-container-template.mmd` - C4 Level 2 (Services, databases)
+- `c4-component-template.mmd` - C4 Level 3 (Internal modules)
+- `sequence-template.mmd` - Interaction flows
+- `er-diagram-template.mmd` - Data models
+- `deployment-template.mmd` - Infrastructure
+
+### Step 4: Generate Diagram
+
+Create diagram with:
+- **Clear title**: Descriptive, includes scope
+- **Consistent naming**: Use kebab-case for IDs
+- **Proper relationships**: Show data flow direction
+- **Annotations**: Add descriptions for context
+- **Boundaries**: Group related components
+- **Valid syntax**: Double-check quotes, parentheses
+
+### Step 5: Validate Syntax
+
+Before returning diagram:
+- ✅ C4 diagrams start with `C4Context` (no `mermaid`)
+- ✅ Other diagrams start with `mermaid`
+- ✅ All elements have descriptions
+- ✅ Relationships have labels
+- ✅ Indentation is correct (2 spaces)
+- ✅ No syntax errors
+
+### Step 6: Specify File Path
+
+Return:
+- **Diagram content**: Valid Mermaid syntax
+- **File path**: Correct location following conventions
+- **Validation instructions**: How user should verify rendering
+
+## Examples
+
+### Example 1: C4 Context Diagram Request
+
+**User**: "Create C4 context diagram for authentication system"
+
+**You**:
+```
+I'll create a C4 Context diagram showing the authentication system boundaries.
+
+File: .specweave/docs/internal/architecture/diagrams/auth-context.mmd
+
+C4Context
+  title Authentication System Context
+
+  Person(user, "User", "A user who needs to authenticate")
+  Person(admin, "Administrator", "Manages user accounts")
+
+  System(auth, "Authentication System", "Handles user authentication, registration, password management")
+
+  System_Ext(email, "Email Service", "Sends verification and password reset emails")
+  System_Ext(sms, "SMS Gateway", "Sends 2FA codes via SMS")
+  System_Ext(oauth, "OAuth Providers", "Google, GitHub, Microsoft identity providers")
+
+  Rel(user, auth, "Authenticates, registers, resets password")
+  Rel(admin, auth, "Manages users, views audit logs")
+  Rel(auth, email, "Sends emails via")
+  Rel(auth, sms, "Sends SMS via")
+  Rel(auth, oauth, "Delegates authentication to")
+
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth-context.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Install Mermaid Preview extension if needed
+3. Verify the diagram renders correctly
+4. Confirm all systems and relationships are visible
+```
+
+### Example 2: Sequence Diagram Request
+
+**User**: "Create sequence diagram for login flow"
+
+**You**:
+```
+I'll create a sequence diagram showing the login authentication flow.
+
+File: .specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd
+
+sequenceDiagram
+    participant User
+    participant Browser
+    participant AuthService
+    participant Database
+    participant SessionStore
+
+    User->>Browser: Enter credentials
+    Browser->>AuthService: POST /api/auth/login
+    activate AuthService
+
+    AuthService->>Database: Query user by email
+    Database-->>AuthService: User record
+
+    AuthService->>AuthService: Verify password (bcrypt)
+
+    alt Password valid
+        AuthService->>SessionStore: Create session
+        SessionStore-->>AuthService: Session ID
+        AuthService-->>Browser: 200 OK + Session cookie
+        Browser-->>User: Redirect to dashboard
+    else Password invalid
+        AuthService-->>Browser: 401 Unauthorized
+        Browser-->>User: Show error message
+    end
+
+    deactivate AuthService
+
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth/flows/login-flow.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Verify the sequence diagram renders correctly
+3. Confirm all participants and messages are clear
+```
+
+### Example 3: ER Diagram Request
+
+**User**: "Create ER diagram for user and session entities"
+
+**You**:
+```
+I'll create an entity-relationship diagram for the authentication data model.
+
+File: .specweave/docs/internal/architecture/diagrams/auth/data-model.mmd
+
+erDiagram
+    USER ||--o{ SESSION : has
+    USER ||--o{ REFRESH_TOKEN : has
+    USER ||--o{ PASSWORD_RESET : requests
+    USER {
+        uuid id PK
+        string email UK
+        string password_hash
+        string first_name
+        string last_name
+        boolean email_verified
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    SESSION {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        string ip_address
+        string user_agent
+        timestamp created_at
+    }
+
+    REFRESH_TOKEN {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        boolean revoked
+        timestamp created_at
+    }
+
+    PASSWORD_RESET {
+        uuid id PK
+        uuid user_id FK
+        string token UK
+        timestamp expires_at
+        boolean used
+        timestamp created_at
+    }
+
+✅ Diagram created: .specweave/docs/internal/architecture/diagrams/auth/data-model.mmd
+
+📋 VALIDATION REQUIRED:
+1. Open the file in VS Code
+2. Verify the ER diagram renders correctly
+3. Confirm relationships and cardinality are accurate
+```
+
+## Common Pitfalls to Avoid
+
+1. ❌ **Using `mermaid` keyword for C4 diagrams** → Use `C4Context` directly
+2. ❌ **Missing quotes in descriptions** → All text must be quoted: `"Description here"`
+3. ❌ **Inconsistent indentation** → Always 2 spaces per level
+4. ❌ **Wrong file locations** → Follow naming conventions exactly
+5. ❌ **Vague titles** → Be specific: "Authentication System Context" not just "Context"
+6. ❌ **No validation instructions** → Always tell user to verify rendering
+7. ❌ **Missing relationships** → Every element should connect to something
+8. ❌ **Unclear labels** → Relationship labels should be verbs: "Uses", "Sends to", "Calls"
+
+## Best Practices
+
+1. ✅ **Start simple** - Begin with high-level C4 Context, then drill down
+2. ✅ **One concept per diagram** - Don't overcrowd diagrams
+3. ✅ **Use consistent naming** - Follow project conventions (kebab-case)
+4. ✅ **Add descriptions** - Every element should have a brief description
+5. ✅ **Show direction** - Make data flow and relationships clear
+6. ✅ **Group related items** - Use boundaries for logical grouping
+7. ✅ **Validate immediately** - Always instruct user to check rendering
+8. ✅ **Reference from docs** - Suggest where diagram should be referenced in documentation
+
+## Integration with diagrams-generator Skill
+
+You will typically be invoked by the `diagrams-generator` skill using the Task tool:
+
+```typescript
+await Task({
+  subagent_type: "diagrams-architect",
+  prompt: "Create C4 context diagram for authentication system",
+  description: "Generate C4 Level 1 diagram"
+});
+```
+
+The skill handles:
+- Detecting diagram requests from user
+- Loading relevant context (specs, docs)
+- Invoking you (the agent)
+- Saving your output to the correct file location
+
+Your responsibility:
+- Generate valid Mermaid diagram syntax
+- Follow all conventions and best practices
+- Provide file path and validation instructions
+- Return diagram content
+
+## Test Cases
+
+See `test-cases/` directory for validation scenarios:
+- `test-1-c4-context.yaml` - C4 Context diagram generation
+- `test-2-sequence.yaml` - Sequence diagram generation
+- `test-3-er-diagram.yaml` - ER diagram generation
+
+## References
+
+See `references/` directory for detailed specifications:
+- `c4-model-spec.md` - Complete C4 Model specification
+- `mermaid-syntax-guide.md` - Mermaid syntax reference for all diagram types
+
+---
+
+**Remember**: If a diagram doesn't render, it doesn't exist. Always validate!

package/src/agents/diagrams-architect/templates/c4-component-template.mmd

@@ -0,0 +1,45 @@
+C4Component
+  title {{SERVICE_NAME}} Component Diagram
+
+  Container(frontend, "{{FRONTEND_NAME}}", "{{FRONTEND_TECH}}", "Web application")
+
+  Container_Boundary(boundary, "{{SERVICE_NAME}}") {
+    Component(controller, "{{CONTROLLER_NAME}}", "{{CONTROLLER_TECH}}", "{{CONTROLLER_DESCRIPTION}}")
+    Component(service, "{{SERVICE_COMPONENT_NAME}}", "{{SERVICE_TECH}}", "{{SERVICE_DESCRIPTION}}")
+    Component(repository, "{{REPOSITORY_NAME}}", "{{REPOSITORY_TECH}}", "{{REPOSITORY_DESCRIPTION}}")
+    Component(validator, "{{VALIDATOR_NAME}}", "{{VALIDATOR_TECH}}", "{{VALIDATOR_DESCRIPTION}}")
+    ComponentDb(cache, "{{CACHE_NAME}}", "Redis", "{{CACHE_DESCRIPTION}}")
+  }
+
+  ContainerDb(database, "{{DATABASE_NAME}}", "{{DB_TECH}}", "Persistent storage")
+
+  %% External interactions
+  Rel(frontend, controller, "Makes API calls", "JSON/HTTPS")
+
+  %% Internal component flow
+  Rel(controller, validator, "Validates input")
+  Rel(controller, service, "Delegates business logic")
+  Rel(service, repository, "Queries data")
+  Rel(service, cache, "Caches results")
+  Rel(repository, database, "Reads/writes", "SQL")
+
+%% Template Variables:
+%% {{SERVICE_NAME}} - Name of the service/container
+%% {{FRONTEND_NAME}} - Frontend application name
+%% {{FRONTEND_TECH}} - Frontend technology
+%% {{CONTROLLER_NAME}} - API controller name (e.g., "AuthController")
+%% {{CONTROLLER_TECH}} - Controller tech (e.g., "Express Router")
+%% {{CONTROLLER_DESCRIPTION}} - What controller handles
+%% {{SERVICE_COMPONENT_NAME}} - Service layer name (e.g., "AuthService")
+%% {{SERVICE_TECH}} - Service technology (e.g., "TypeScript Class")
+%% {{SERVICE_DESCRIPTION}} - Business logic handled
+%% {{REPOSITORY_NAME}} - Data access layer name (e.g., "UserRepository")
+%% {{REPOSITORY_TECH}} - Repository tech (e.g., "Prisma ORM")
+%% {{REPOSITORY_DESCRIPTION}} - Data operations handled
+%% {{VALIDATOR_NAME}} - Validator name (e.g., "InputValidator")
+%% {{VALIDATOR_TECH}} - Validation tech (e.g., "Zod")
+%% {{VALIDATOR_DESCRIPTION}} - What is validated
+%% {{CACHE_NAME}} - Cache component name
+%% {{CACHE_DESCRIPTION}} - What is cached
+%% {{DATABASE_NAME}} - Database name
+%% {{DB_TECH}} - Database technology

package/src/agents/diagrams-architect/templates/c4-container-template.mmd

@@ -0,0 +1,48 @@
+C4Container
+  title {{SYSTEM_NAME}} Container Diagram
+
+  Person(user, "{{USER_TYPE}}", "{{USER_DESCRIPTION}}")
+
+  System_Boundary(boundary, "{{SYSTEM_NAME}}") {
+    Container(webapp, "{{WEB_APP_NAME}}", "{{WEB_TECH}}", "{{WEB_APP_DESCRIPTION}}")
+    Container(api, "{{API_NAME}}", "{{API_TECH}}", "{{API_DESCRIPTION}}")
+    Container(worker, "{{WORKER_NAME}}", "{{WORKER_TECH}}", "{{WORKER_DESCRIPTION}}")
+    ContainerDb(db, "{{DATABASE_NAME}}", "{{DB_TECH}}", "{{DATABASE_DESCRIPTION}}")
+    ContainerDb(cache, "{{CACHE_NAME}}", "Redis", "{{CACHE_DESCRIPTION}}")
+  }
+
+  System_Ext(external, "{{EXTERNAL_SYSTEM}}", "{{EXTERNAL_DESCRIPTION}}")
+
+  %% User interactions
+  Rel(user, webapp, "{{USER_WEB_INTERACTION}}", "HTTPS")
+
+  %% Internal relationships
+  Rel(webapp, api, "{{WEB_TO_API}}", "JSON/HTTPS")
+  Rel(api, db, "Reads/writes data", "SQL/TCP")
+  Rel(api, cache, "Caches data", "Redis Protocol")
+  Rel(api, worker, "Queues jobs", "Message Queue")
+  Rel(worker, db, "Reads/writes data", "SQL/TCP")
+
+  %% External integrations
+  Rel(api, external, "{{API_TO_EXTERNAL}}", "HTTPS")
+
+%% Template Variables:
+%% {{SYSTEM_NAME}} - Name of your system
+%% {{USER_TYPE}} - Type of user
+%% {{USER_DESCRIPTION}} - User description
+%% {{WEB_APP_NAME}} - Frontend application name
+%% {{WEB_TECH}} - Frontend tech stack (e.g., "React, TypeScript")
+%% {{WEB_APP_DESCRIPTION}} - What the frontend does
+%% {{API_NAME}} - Backend API name
+%% {{API_TECH}} - Backend tech stack (e.g., "Node.js, Express")
+%% {{API_DESCRIPTION}} - What the API does
+%% {{WORKER_NAME}} - Background worker name
+%% {{WORKER_TECH}} - Worker tech (e.g., "Node.js, Bull")
+%% {{WORKER_DESCRIPTION}} - What worker processes
+%% {{DATABASE_NAME}} - Database name
+%% {{DB_TECH}} - Database technology (e.g., "PostgreSQL", "MongoDB")
+%% {{DATABASE_DESCRIPTION}} - What data is stored
+%% {{CACHE_NAME}} - Cache name
+%% {{CACHE_DESCRIPTION}} - What is cached
+%% {{EXTERNAL_SYSTEM}} - External system name
+%% {{EXTERNAL_DESCRIPTION}} - External system description

package/src/agents/diagrams-architect/templates/c4-context-template.mmd

@@ -0,0 +1,29 @@
+C4Context
+  title {{SYSTEM_NAME}} System Context
+
+  %% External Users/Actors
+  Person(user, "{{USER_TYPE}}", "{{USER_DESCRIPTION}}")
+  Person(admin, "Administrator", "Manages the system")
+
+  %% Main System
+  System(system, "{{SYSTEM_NAME}}", "{{SYSTEM_DESCRIPTION}}")
+
+  %% External Systems
+  System_Ext(external1, "{{EXTERNAL_SYSTEM_1}}", "{{EXTERNAL_DESCRIPTION_1}}")
+  System_Ext(external2, "{{EXTERNAL_SYSTEM_2}}", "{{EXTERNAL_DESCRIPTION_2}}")
+
+  %% Relationships
+  Rel(user, system, "{{USER_INTERACTION}}")
+  Rel(admin, system, "Manages and configures")
+  Rel(system, external1, "{{INTEGRATION_1}}")
+  Rel(system, external2, "{{INTEGRATION_2}}")
+
+%% Template Variables:
+%% {{SYSTEM_NAME}} - Name of your system
+%% {{SYSTEM_DESCRIPTION}} - Brief description of what the system does
+%% {{USER_TYPE}} - Type of user (e.g., "Customer", "Developer")
+%% {{USER_DESCRIPTION}} - Description of the user role
+%% {{USER_INTERACTION}} - How user interacts with system
+%% {{EXTERNAL_SYSTEM_*}} - Names of external systems
+%% {{EXTERNAL_DESCRIPTION_*}} - Descriptions of external systems
+%% {{INTEGRATION_*}} - How your system integrates with external systems

package/src/agents/diagrams-architect/templates/deployment-template.mmd

@@ -0,0 +1,77 @@
+C4Deployment
+  title {{SYSTEM_NAME}} Deployment Diagram - {{ENVIRONMENT}}
+
+  Deployment_Node(cloud, "{{CLOUD_PROVIDER}}", "Cloud Platform") {
+    Deployment_Node(region, "{{REGION}}", "Geographic Region") {
+
+      Deployment_Node(cdn, "CDN", "Content Delivery Network") {
+        Container(static, "{{STATIC_ASSETS}}", "Static Files", "{{STATIC_DESCRIPTION}}")
+      }
+
+      Deployment_Node(compute, "{{COMPUTE_SERVICE}}", "Compute") {
+        Deployment_Node(web_cluster, "Web Cluster", "Auto-scaling group") {
+          Container(webapp, "{{WEB_APP}}", "{{WEB_TECH}}", "{{WEB_DESCRIPTION}}")
+        }
+
+        Deployment_Node(api_cluster, "API Cluster", "Auto-scaling group") {
+          Container(api, "{{API_NAME}}", "{{API_TECH}}", "{{API_DESCRIPTION}}")
+        }
+
+        Deployment_Node(worker_cluster, "Worker Cluster", "Auto-scaling group") {
+          Container(worker, "{{WORKER_NAME}}", "{{WORKER_TECH}}", "{{WORKER_DESCRIPTION}}")
+        }
+      }
+
+      Deployment_Node(database, "{{DATABASE_SERVICE}}", "Managed Database") {
+        ContainerDb(db, "{{DB_NAME}}", "{{DB_TECH}}", "{{DB_DESCRIPTION}}")
+      }
+
+      Deployment_Node(cache, "{{CACHE_SERVICE}}", "Managed Cache") {
+        ContainerDb(redis, "{{CACHE_NAME}}", "Redis", "{{CACHE_DESCRIPTION}}")
+      }
+
+      Deployment_Node(queue, "{{QUEUE_SERVICE}}", "Message Queue") {
+        Container(mq, "{{QUEUE_NAME}}", "{{QUEUE_TECH}}", "{{QUEUE_DESCRIPTION}}")
+      }
+    }
+  }
+
+  Deployment_Node(monitoring, "{{MONITORING_SERVICE}}", "Observability Platform") {
+    Container(logs, "{{LOGGING_SERVICE}}", "Centralized Logging", "{{LOGGING_DESCRIPTION}}")
+    Container(metrics, "{{METRICS_SERVICE}}", "Metrics & Alerting", "{{METRICS_DESCRIPTION}}")
+  }
+
+  %% Relationships
+  Rel(webapp, api, "API calls", "HTTPS")
+  Rel(api, db, "Queries", "PostgreSQL Protocol")
+  Rel(api, redis, "Caches", "Redis Protocol")
+  Rel(api, mq, "Publishes jobs", "AMQP")
+  Rel(worker, mq, "Consumes jobs", "AMQP")
+  Rel(worker, db, "Updates data", "PostgreSQL Protocol")
+
+  %% Monitoring
+  Rel(webapp, logs, "Ships logs", "HTTP")
+  Rel(api, logs, "Ships logs", "HTTP")
+  Rel(worker, logs, "Ships logs", "HTTP")
+  Rel(webapp, metrics, "Exports metrics", "Prometheus")
+  Rel(api, metrics, "Exports metrics", "Prometheus")
+
+%% Template Variables:
+%% {{SYSTEM_NAME}} - Name of your system
+%% {{ENVIRONMENT}} - Environment name (Production, Staging, Development)
+%% {{CLOUD_PROVIDER}} - Cloud provider (AWS, Azure, GCP, Hetzner)
+%% {{REGION}} - Geographic region (us-east-1, eu-central-1, etc.)
+%% {{COMPUTE_SERVICE}} - Compute service (ECS, Kubernetes, VMs)
+%% {{DATABASE_SERVICE}} - Database service (RDS, Cloud SQL, Managed PostgreSQL)
+%% {{CACHE_SERVICE}} - Cache service (ElastiCache, Memorystore)
+%% {{QUEUE_SERVICE}} - Queue service (SQS, Pub/Sub, RabbitMQ)
+%% {{MONITORING_SERVICE}} - Monitoring platform (CloudWatch, Datadog, Grafana)
+%% {{*_NAME}} - Component names
+%% {{*_TECH}} - Technologies used
+%% {{*_DESCRIPTION}} - Component descriptions
+
+%% Common Cloud Services by Provider:
+%% AWS: ECS, RDS, ElastiCache, SQS, CloudWatch
+%% Azure: App Service, Azure SQL, Redis Cache, Service Bus, Application Insights
+%% GCP: Cloud Run, Cloud SQL, Memorystore, Pub/Sub, Cloud Logging
+%% Hetzner: Cloud Servers, Managed PostgreSQL, Object Storage

package/src/agents/diagrams-architect/templates/er-diagram-template.mmd

@@ -0,0 +1,64 @@
+erDiagram
+    {{ENTITY_1}} ||--o{ {{ENTITY_2}} : {{RELATIONSHIP_1}}
+    {{ENTITY_2}} }o--|| {{ENTITY_3}} : {{RELATIONSHIP_2}}
+    {{ENTITY_1}} ||--o{ {{ENTITY_3}} : {{RELATIONSHIP_3}}
+
+    {{ENTITY_1}} {
+        uuid id PK "Primary key"
+        string {{FIELD_1}} UK "Unique constraint"
+        string {{FIELD_2}} "Required field"
+        int {{FIELD_3}} "Numeric field"
+        boolean {{FIELD_4}} "Boolean flag"
+        timestamp created_at "Creation timestamp"
+        timestamp updated_at "Last update timestamp"
+    }
+
+    {{ENTITY_2}} {
+        uuid id PK
+        uuid {{FK_TO_ENTITY_1}} FK "Foreign key to {{ENTITY_1}}"
+        string {{FIELD_5}}
+        text {{FIELD_6}} "Long text field"
+        enum {{FIELD_7}} "Enum type"
+        decimal {{FIELD_8}} "Decimal number"
+        date {{FIELD_9}} "Date only"
+        timestamp created_at
+    }
+
+    {{ENTITY_3}} {
+        uuid id PK
+        uuid {{FK_TO_ENTITY_1}} FK
+        uuid {{FK_TO_ENTITY_2}} FK
+        json {{FIELD_10}} "JSON data"
+        timestamp {{FIELD_11}}
+        timestamp created_at
+        timestamp updated_at
+    }
+
+%% Template Variables:
+%% {{ENTITY_*}} - Entity/table names (UPPERCASE convention)
+%% {{RELATIONSHIP_*}} - Relationship descriptions (e.g., "has", "belongs to")
+%% {{FIELD_*}} - Field names (snake_case convention)
+%% {{FK_TO_*}} - Foreign key field names
+
+%% Relationship Cardinality:
+%% ||--|| : one to one
+%% ||--o{ : one to many
+%% }o--|| : many to one
+%% }o--o{ : many to many
+
+%% Field Constraints:
+%% PK : Primary Key
+%% FK : Foreign Key
+%% UK : Unique Key
+
+%% Common Field Types:
+%% - uuid, int, bigint, string, text
+%% - boolean, enum, json
+%% - decimal, float, money
+%% - date, time, timestamp, datetime
+
+%% Best Practices:
+%% - Always include id (PK), created_at, updated_at
+%% - Use uuid for distributed systems
+%% - Add field comments for clarity
+%% - Show foreign key relationships clearly