# System Design Standards > **Tier 2 — Skill-local standards.** Extends [Core Standards (Tier 1)](../../standards/core.md). Core standards apply universally; this file adds cognia-arch–specific HTML templates and diagram conventions. Reference templates for producing the `{project_name}-architecture.html` file. Use these as starting points — **replace all placeholder node labels** with the actual system components discovered during analysis. > ⚠️ **CRITICAL FILE RULE**: Always **overwrite** `{project_name}-architecture.html` completely — NEVER append to it. > If the file already exists, replace its entire contents. Two complete HTML documents in one file will break rendering. --- ## HTML + Mermaid.js Page Template This is the base HTML structure for `{project_name}-architecture.html`. Populate all `
` blocks with diagrams from the analysis.

Use the **warm light design system** — warm cream/amber palette: `#7c4a1e` primary, `#b97230` secondary, `#d4872a` accent, `#fdfaf5` background, no dark backgrounds anywhere. Mermaid uses `theme: 'default'` with `fontFamily: 'system-ui, Segoe UI, sans-serif'`.

```html



  
  
  Architecture
  
  
  
  





  
Project System Architecture

  
Project architecture diagrams







  

    
1. High-Level Architecture

    

      
System Boundary Overview

      
graph TB
    subgraph "Clients"
        UI[Web UI]
        Mobile[Mobile Client]
    end
    subgraph "Application Server"
        APP[Monolithic Application]
        BIZ[Business Logic Layer]
        DAL[Data Access Layer]
    end
    subgraph "Infrastructure"
        DB[(Relational Database)]
        FS[File System]
        MQ[Message Queue]
    end
    subgraph "External Systems"
        LDAP["LDAP / SSO"]
        EXT[External APIs]
        EMAIL[Email Server]
    end
    UI --> APP
    Mobile --> APP
    APP --> BIZ
    BIZ --> DAL
    DAL --> DB
    DAL --> FS
    BIZ --> MQ
    APP --> LDAP
    BIZ --> EXT
    BIZ --> EMAIL
      

    

  


  

    
2. Component Dependency Diagram

    

      
Module Dependencies

      
graph LR
    subgraph "Core Modules"
        AUTH[Auth Module]
        CORE[Core Business Module]
        REPORT[Reporting Module]
    end
    subgraph "Supporting"
        UTIL["Utility / Helpers"]
        CONFIG[Config Module]
        LOG[Logging Module]
    end
    CORE --> AUTH
    CORE --> UTIL
    CORE --> CONFIG
    REPORT --> CORE
    AUTH --> LDAP_INT[LDAP Integration]
    LOG -.->|cross-cutting| CORE
    LOG -.->|cross-cutting| AUTH
    LOG -.->|cross-cutting| REPORT
      

    

  


  

    
3. Data Flow Diagram

    

      
Request Processing Flow

      
flowchart TD
    INPUT[User Request] --> VALIDATION[Input Validation]
    VALIDATION --> AUTH_CHK{"Authorized?"}
    AUTH_CHK -- No --> ERROR["Return 401/403"]
    AUTH_CHK -- Yes --> BUSINESS[Business Processing]
    BUSINESS --> DB_READ[(DB Read)]
    BUSINESS --> DB_WRITE[(DB Write)]
    BUSINESS --> EXT_CALL[External System Call]
    DB_WRITE --> RESPONSE[Response to Client]
    EXT_CALL --> RESPONSE
      

    

  


  

    
4. Authentication Flow

    

      
Login & Session Sequence

      
sequenceDiagram
    participant U as User
    participant APP as Application
    participant LDAP as "LDAP Server"
    participant DB as Database
    U->>APP: Login Request (username/password)
    APP->>LDAP: Bind + Authenticate
    LDAP-->>APP: Auth Result
    alt Auth Success
        APP->>DB: Load User Roles
        DB-->>APP: Roles / Permissions
        APP-->>U: Session Token / Cookie
    else Auth Failure
        APP-->>U: 401 Unauthorized
    end
      

    

  


  

    
5. Database Architecture

    

      
Entity Relationship Overview

      
erDiagram
    CUSTOMERS ||--o{ ORDERS : places
    ORDERS ||--|{ ORDER_LINES : contains
    ORDER_LINES }o--|| PRODUCTS : references
    CUSTOMERS ||--o{ ADDRESSES : has
      

    

  


  

    
6. Deployment Topology

    

      
Infrastructure & Network Zones

      
graph TD
    subgraph DMZ
        LB[Load Balancer nginx]
        CDN[CDN CloudFront]
    end
    subgraph AppTier
        APP1[App Server 1]
        APP2[App Server 2]
    end
    subgraph DBTier
        DB[(PostgreSQL Primary)]
        DBreplica[(PostgreSQL Replica)]
    end
    CDN --> LB
    LB --> APP1
    LB --> APP2
    APP1 --> DB
    APP2 --> DB
    DB --> DBreplica
      

    

  










```

---

## Mermaid Syntax Rules & Common Errors

Follow these rules strictly when populating diagram blocks to prevent rendering failures.

### Rule 1 — Use `
` (not `
`)

✅ Correct:
```html

graph TB
    A --> B


```
❌ Incorrect — browser may HTML-parse content before Mermaid processes it:
```html


graph TB
    A --> B


```

### Rule 2 — Line Breaks in Node Labels

With `htmlLabels: true`, use `
` not `\n` for line breaks inside quoted node labels.

✅ `A["Line One
Line Two"]`  
❌ `A["Line One\nLine Two"]` — renders as the literal characters `\n`

### Rule 3 — Node ID Rules

| Rule | Correct | Incorrect |
|---|---|---|
| No spaces in IDs | `AUTH_SRV[Auth Service]` | `AUTH SRV[Auth Service]` |
| Reserved words as IDs | `END_NODE[End]` | `end[End]` (reserved keyword) |
| Special chars in labels | `A["My (Node)"]` | `A[My (Node)]` |
| Slash in labels | `A["LDAP / SSO"]` | `A[LDAP / SSO]` |
| Question mark in diamond | `A{"Done?"}` | `A{Done?}` |
| Slash in diamond | `A{"401/403"}` | `A{401/403}` |

### Rule 4 — Participant Names with Special Characters (sequenceDiagram)

Quote participant display names that contain parentheses, commas, slashes, spaces, or any other characters that could be ambiguous:

✅ `participant LDAP as "LDAP Server"`  
✅ `participant IDP as "Identity Provider (LDAP/Keycloak)"`  
❌ `participant LDAP as LDAP Server`  
❌ `participant IDP as Identity Provider (LDAP/Keycloak)`

### Rule 5 — Always Close `subgraph` and `alt`/`loop` Blocks

Every `subgraph` must end with `end`.  
Every `alt`, `else`, `loop`, `opt` in sequenceDiagram must have a matching `end`.

### Rule 6 — One Diagram Type Per Block

Each `
` block must contain exactly one diagram.  
Valid openers: `graph TB`, `graph LR`, `flowchart TD`, `sequenceDiagram`, `classDiagram`, `erDiagram`

### Rule 7 — erDiagram Syntax

| Rule | Correct | Incorrect |
|---|---|---|
| Relationship label must be quoted with `""` if multi-word | `ORDERS ||--o{ LINES : "contains items"` | `ORDERS ||--o{ LINES : contains items` |
| Relationship label must not be empty | `A ||--o{ B : places` | `A ||--o{ B :` |
| Entity names — no spaces | `ORDER_LINES` | `ORDER LINES` |
| Valid cardinality symbols | `\|\|`, `\|o`, `o\|`, `}{`, `\|{`, `}o`, `o{`, `oo` | any other form |
| Each entity definition on its own line | one entity per line | multiple on same line |
| No `subgraph` inside erDiagram | use entity grouping via naming convention | `subgraph "Module"` inside erDiagram |
| Column definitions (optional) are inside `{}` on own lines | `ORDERS { int id PK \n string status }` | columns inline with relationship |

✅ Correct erDiagram example:
```
erDiagram
    CUSTOMERS ||--o{ ORDERS : places
    ORDERS ||--|{ ORDER_LINES : contains
    ORDER_LINES }o--|| PRODUCTS : references
    CUSTOMERS ||--o{ ADDRESSES : has
```

❌ Common errors:
- `ORDERS ||--o{ ORDER_LINES : contains items` — unquoted multi-word label → wrap in `""`: `"contains items"`
- `CUSTOMERS ||--o{ ORDERS :` — empty label → provide a verb: `places`
- `ORDER LINES` — space in entity name → use `ORDER_LINES`

### Rule 8 — Panzoom Script (MANDATORY)

> ⚠️ **The panzoom script is required in EVERY generated HTML file.** Never omit it.

The `` must include:
```html

```

The closing `` appears in `` AND the full panzoom initialisation block (toolbar buttons + `panzoom(svg, ...)` call) appears before ``

If any check fails, **overwrite the entire file** with corrected content using `create_file` — never patch individual lines.

---

## Output Document Structure (`{project_name}-architecture.md`)

```markdown
# System Architecture

## 1. Architectural Style
[Describe: monolith / distributed / client-server / SOA / etc.]

## 2. Module Inventory
### 2.1 Module List with Responsibilities
| Module | Responsibility | Technology | Owner |
|---|---|---|---|

### 2.2 Module Dependency Matrix
[Table: which modules depend on which]

## 3. Communication Patterns
### 3.1 Synchronous Calls
### 3.2 Asynchronous Flows
### 3.3 Database Coupling Points

## 4. Cross-Cutting Concerns
[Logging, Auth, Error Handling, Config]

## 5. Architectural Weaknesses
| # | Weakness | Evidence | Impact | Migration Risk |
|---|---|---|---|---|

## 6. Coupling Hotspots
[List tightest dependencies]

## 7. Constraints for New Design
[Hard constraints that must be respected]
```

---

## Architectural Weakness Table Template

| # | Weakness | Evidence | Impact | Migration Risk |
|---|---|---|---|---|
| 1 | Shared database between modules | Multiple modules write to `USERS` table | High coupling | High |
| 2 | Business logic in stored procedures | 40+ stored procs with complex logic | Hard to test/migrate | High |
| 3 | Hard-coded configuration | DB URLs in source code | Security risk | Medium |

Use `High / Medium / Low` for Impact and Migration Risk columns.