Initial commit

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

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

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

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

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

agents/diagrams-architect/templates/sequence-template.mmd

@@ -0,0 +1,55 @@
+sequenceDiagram
+    participant {{ACTOR_1}} as {{ACTOR_1_NAME}}
+    participant {{ACTOR_2}} as {{ACTOR_2_NAME}}
+    participant {{ACTOR_3}} as {{ACTOR_3_NAME}}
+    participant {{ACTOR_4}} as {{ACTOR_4_NAME}}
+
+    {{ACTOR_1}}->>{{ACTOR_2}}: {{STEP_1_ACTION}}
+    activate {{ACTOR_2}}
+
+    {{ACTOR_2}}->>{{ACTOR_3}}: {{STEP_2_ACTION}}
+    activate {{ACTOR_3}}
+
+    {{ACTOR_3}}->>{{ACTOR_4}}: {{STEP_3_ACTION}}
+    {{ACTOR_4}}-->>{{ACTOR_3}}: {{STEP_3_RESPONSE}}
+
+    {{ACTOR_3}}-->>{{ACTOR_2}}: {{STEP_2_RESPONSE}}
+    deactivate {{ACTOR_3}}
+
+    alt {{SUCCESS_CONDITION}}
+        {{ACTOR_2}}-->>{{ACTOR_1}}: {{SUCCESS_RESPONSE}}
+        {{ACTOR_1}}->>{{ACTOR_1}}: {{SUCCESS_ACTION}}
+    else {{FAILURE_CONDITION}}
+        {{ACTOR_2}}-->>{{ACTOR_1}}: {{ERROR_RESPONSE}}
+        {{ACTOR_1}}->>{{ACTOR_1}}: {{ERROR_ACTION}}
+    end
+
+    deactivate {{ACTOR_2}}
+
+    %% Optional: Loop example
+    %% loop {{LOOP_CONDITION}}
+    %%     {{ACTOR}}->>{{TARGET}}: {{LOOP_ACTION}}
+    %% end
+
+    %% Optional: Note example
+    %% Note over {{ACTOR_1}},{{ACTOR_2}}: {{NOTE_TEXT}}
+
+%% Template Variables:
+%% {{ACTOR_*}} - Short identifier for participant
+%% {{ACTOR_*_NAME}} - Display name for participant
+%% {{STEP_*_ACTION}} - Action/message description
+%% {{STEP_*_RESPONSE}} - Response message
+%% {{SUCCESS_CONDITION}} - Condition for success path
+%% {{FAILURE_CONDITION}} - Condition for error path
+%% {{SUCCESS_RESPONSE}} - Success message
+%% {{SUCCESS_ACTION}} - Action on success
+%% {{ERROR_RESPONSE}} - Error message
+%% {{ERROR_ACTION}} - Action on error
+
+%% Notes:
+%% - Use activate/deactivate to show processing time
+%% - Use alt/else for conditional flows
+%% - Use loop for repeated actions
+%% - Use Note over for explanations
+%% - Solid arrow (->>) for requests
+%% - Dashed arrow (-->>) for responses