# securecodewarrior/ai-security-rules architecture

> Architecture diagram of the GitHub repository securecodewarrior/ai-security-rules, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/securecodewarrior/ai-security-rules
- Repository: https://github.com/securecodewarrior/ai-security-rules

## Overview

##### What this project is (type + purpose)
This repo is **not an application runtime** (no services, no binaries, no deployable code). It’s a **rule-pack / documentation repository** that publishes **security instruction files** intended to be copied into other repositories so that **AI coding assistants** (Copilot, Cursor, Windsurf, Cline, Roo, Aider) produce safer, more compliant code.

- **A content source-of-truth (this repo)**
- **Distribution / installation into target codebases**
- **Consumption by AI assistants inside developer tools**
- **Resulting influence on code generation + review loops**

This is essentially an “AI SDLC guardrails” architecture.

##### File tree analysis (what to represent)
Top-level artifacts:
- `README.md` — explains what rules are, why they exist, and how to install them per tool.
- `backend.md` — platform rule set (server-side)
- `frontend.md` — platform rule set (client-side)
- `mobile.md` — platform rule set (mobile apps)
- `language-specific/`
- `python.md` — language rule set for Python
- `javascript.md` — language rule set for JavaScript
- `assets/` — marketing/visuals (banner), not part of functional architecture but can appear as “documentation assets”.

Architecturally, the repo is organized as **rule modules by domain**:
- Platform-specific modules (backend/frontend/mobile)
- Language-specific modules (python/javascript)

##### What the README implies about runtime interactions
- Rules are **copied** into a **target project repository** in a **tool-specific path**:
- Copilot: `.github/copilot-instructions.md`
- Cursor: `.cursor/rules`
- Windsurf: `.windsurfrules`
- Cline: `.clinerules`
- Roo: `.roorules`
- Aider: `CONVENTIONS.md` + referenced from `.aider.conf.yml`
- Tools can apply rules **always or conditionally** based on metadata (important for showing “rule selection / triggering”).

So the “system” is a **pipeline of influence**:
SCW Rules Repo → (copy/install) → Target Codebase → AI Tool reads rules → AI generates code under constraints → Developers review/commit → Feedback leads to rule updates (new versions).

##### AI Coding Assistants (Copilot/Cursor/Windsurf/Cline/Roo/Aider)
5) (Optional but realistic) **AI Model/Provider** behind the assistant (e.g., hosted LLM) — not in the repo, but relevant to show where prompts go.
6) **SDLC Controls** (code review, CI, SAST) — also not in this repo, but important to show the “guardrail sits alongside other controls” relationship.

**Level 2: Containers (inside the “Rules Repo”)**
Break the repo into modules:
- Platform Rules:
- `backend.md`
- `frontend.md`
- `mobile.md`
- Language Rules:
- `language-specific/python.md`
- `language-specific/javascript.md`
- Documentation & Assets:
- `README.md`
- `assets/`

**Level 2: Containers (inside the “Target Project”)**
“rule installation targets” as containers/paths:
- `.github/copilot-instructions.md`
- `.cursor/rules`
- `.windsurfrules`
- `.clinerules`
- `.roorules`
- `CONVENTIONS.md` + `.aider.conf.yml`

This is critical: for this project, **file placement is the integration mechanism**.

##### Copy/Adopt flow (human-mediated)
- Developer → copies selected SCW rule file(s) → Target Project specific location
- Notes: “manual copy” or “automated via internal template / repo bootstrap” (if your org does that).

##### Rule ingestion (tool behavior)
- AI Assistant (inside IDE/editor) → reads rules from repo paths → uses them as system/developer instructions
- Optional: include “metadata triggers” as a decision diamond: “apply always?” / “apply conditionally?”

##### Prompt + context assembly
- AI Assistant → sends prompt (code context + rules) → LLM provider/service → returns suggestion

##### Output application
- Developer → accepts/modifies suggestion → commits code
- Code review/CI may catch issues; add a feedback loop: “If recurring violations, update rules.”

##### Rules evolution
- Findings/feedback from devs/security → updates to SCW rules repo → version bump (repo currently at **1.2.0**)

##### Architectural patterns/design principles to call out
- **Policy-as-code / Guidance-as-code**: rules are textual artifacts that behave like policy inputs to tools.
- **Modular rule composition**: choose backend + language-specific, etc.
- **Tool adapter pattern**: same conceptual rules mapped into different tool-specific file locations/formats.
- **Shift-left security enablement**: rules apply at authoring time, earlier than CI scanning.

Even though there’s no runtime framework, include:
- AI tools: GitHub Copilot, Cursor, Windsurf, Cline, Roo, Aider
- Integration points: file-based configuration paths listed above
- (Optional) LLM provider node (generic “LLM API/Service”)

##### Don’t overthink it: “separate into as many components as possible”
For *this* project, “more components” primarily means:
- Break rules into their **actual files** (backend/frontend/mobile/python/javascript)
- Break integrations into **actual installation targets** (one per tool)
- AI tool as its own node (because behavior differs)
- **human workflow nodes** (install, configure metadata, accept suggestions, update rules)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% ========== System Context (Vertical) ==========
  Dev(["Developer / Team"]):::human
  Sec(["Security / Compliance Reviewer"]):::human
  SDLC["SDLC Controls\n(CodeReview • CI • SAST/Linters)"]:::control

  subgraph "SCW AI Security Rules Repository (v1.2.0)"
    Repo[("Source-of-truth Repo")]:::repo

    subgraph "Rule Modules (Markdown)"
      Backend["backend.md\n(Platform Rules: Backend)"]:::rule
      Frontend["frontend.md\n(Platform Rules: Frontend)"]:::rule
      Mobile["mobile.md\n(Platform Rules: Mobile)"]:::rule
      subgraph "language-specific/ (Language Rules)"
        LangDir[("language-specific/")]:::folder
        Py["python.md\n(Language Rules: Python)"]:::rule
        JS["javascript.md\n(Language Rules: JavaScript)"]:::rule
      end
    end

    Readme["README.md\n(Install/Usage Docs)"]:::doc
    Assets[("assets/\n(Visual/Marketing Assets)")]:::asset
  end

  subgraph "Target Software Project Repository"
    TargetRepo[("Target Repo (Codebase)")]:::target

    subgraph "Installed AI Instruction Files (Tool-specific paths)"
      CopilotFile[".github/copilot-instructions.md"]:::install
      CursorRules[".cursor/rules"]:::install
      WindsurfRules[".windsurfrules"]:::install
      ClineRules[".clinerules"]:::install
      RooRules[".roorules"]:::install
      AiderConv["CONVENTIONS.md"]:::install
      AiderConf[".aider.conf.yml\n(references CONVENTIONS.md)"]:::install
    end

    Code["Source Code\n(app/services/tests)"]:::code
  end

  subgraph "Developer Environment (IDE/Editor)"
    IDE["IDE / Editor"]:::env

    subgraph "AI Coding Assistants (Plugins)"
      Copilot["GitHub Copilot"]:::tool
      Cursor["Cursor"]:::tool
      Windsurf["Windsurf"]:::tool
      Cline["Cline"]:::tool
      Roo["Roo"]:::tool
      Aider["Aider"]:::tool
    end

    Trigger{"Rule Selection\nAlways or Conditional\n(metadata/triggers)"}:::decision
  end

  LLM["LLM Service / Provider\n(API)"]:::llm

  %% ========== Adopt / Install Flow (dashed) ==========
  Dev -.->|"selects_modules"| Backend
  Dev -.->|"selects_modules"| Frontend
  Dev -.->|"selects_modules"| Mobile
  Dev -.->|"selects_modules"| Py
  Dev -.->|"selects_modules"| JS
  Dev -.->|"reads_install_guidance"| Readme

  Backend -.->|"copy/install"| CopilotFile
  Frontend -.->|"copy/install"| CopilotFile
  Mobile -.->|"copy/install"| CopilotFile
  Py -.->|"copy/install"| CopilotFile
  JS -.->|"copy/install"| CopilotFile

  Backend -.->|"copy/install"| CursorRules
  Frontend -.->|"copy/install"| CursorRules
  Mobile -.->|"copy/install"| CursorRules
  Py -.->|"copy/install"| CursorRules
  JS -.->|"copy/install"| CursorRules

  Backend -.->|"copy/install"| WindsurfRules
  Frontend -.->|"copy/install"| WindsurfRules
  Mobile -.->|"copy/install"| WindsurfRules
  Py -.->|"copy/install"| WindsurfRules
  JS -.->|"copy/install"| WindsurfRules

  Backend -.->|"copy/install"| ClineRules
  Frontend -.->|"copy/install"| ClineRules
  Mobile -.->|"copy/install"| ClineRules
  Py -.->|"copy/install"| ClineRules
  JS -.->|"copy/install"| ClineRules

  Backend -.->|"copy/install"| RooRules
  Frontend -.->|"copy/install"| RooRules
  Mobile -.->|"copy/install"| RooRules
  Py -.->|"copy/install"| RooRules
  JS -.->|"copy/install"| RooRules

  Backend -.->|"copy/install"| AiderConv
  Frontend -.->|"copy/install"| AiderConv
  Mobile -.->|"copy/install"| AiderConv
  Py -.->|"copy/install"| AiderConv
  JS -.->|"copy/install"| AiderConv
  Dev -.->|"configure_reference"| AiderConf
  AiderConf -.->|"references"| AiderConv

  %% ========== Runtime / Consumption Flow (solid) ==========
  Dev -->|"uses"| IDE

  IDE -->|"invokes"| Copilot
  IDE -->|"invokes"| Cursor
  IDE -->|"invokes"| Windsurf
  IDE -->|"invokes"| Cline
  IDE -->|"invokes"| Roo
  IDE -->|"invokes"| Aider

  Copilot -->|"reads_rules"| CopilotFile
  Cursor -->|"reads_rules"| CursorRules
  Windsurf -->|"reads_rules"| WindsurfRules
  Cline -->|"reads_rules"| ClineRules
  Roo -->|"reads_rules"| RooRules
  Aider -->|"reads_rules"| AiderConv
  Aider -->|"reads_config"| AiderConf

  Copilot --> Trigger
  Cursor --> Trigger
  Windsurf --> Trigger
  Cline --> Trigger
  Roo --> Trigger
  Aider --> Trigger

  Trigger -->|"builds_prompt\n(rules+code_context)"| LLM
  LLM -->|"returns_suggestions"| Trigger

  Trigger -->|"suggests_changes"| IDE
  IDE -->|"applies_edits"| Code
  Code -->|"commit_PR"| SDLC

  %% ========== Feedback Loop (dashed) ==========
  SDLC -.->|"findings/violations"| Sec
  Sec -.->|"feedback"| Dev
  Dev -.->|"update_rules"| Repo

  %% ========== Click Events (from component_mapping) ==========
  click Repo "https://github.com/securecodewarrior/ai-security-rules/tree/main/./"
  click Readme "https://github.com/securecodewarrior/ai-security-rules/blob/main/README.md"
  click Backend "https://github.com/securecodewarrior/ai-security-rules/blob/main/backend.md"
  click Frontend "https://github.com/securecodewarrior/ai-security-rules/blob/main/frontend.md"
  click Mobile "https://github.com/securecodewarrior/ai-security-rules/blob/main/mobile.md"
  click LangDir "https://github.com/securecodewarrior/ai-security-rules/tree/main/language-specific/"
  click Py "https://github.com/securecodewarrior/ai-security-rules/blob/main/language-specific/python.md"
  click JS "https://github.com/securecodewarrior/ai-security-rules/blob/main/language-specific/javascript.md"
  click Assets "https://github.com/securecodewarrior/ai-security-rules/tree/main/assets/"

  %% ========== Styles ==========
  classDef repo fill:#1f4e79,stroke:#0b2a3d,color:#ffffff,stroke-width:1px;
  classDef rule fill:#2f6f9f,stroke:#0b2a3d,color:#ffffff,stroke-width:1px;
  classDef doc fill:#1e6f5c,stroke:#0d3a30,color:#ffffff,stroke-width:1px;
  classDef asset fill:#6c757d,stroke:#3a3f44,color:#ffffff,stroke-width:1px;
  classDef target fill:#3c3f44,stroke:#1f2326,color:#ffffff,stroke-width:1px;
  classDef install fill:#f4b183,stroke:#8a4f00,color:#1f2326,stroke-width:1px;
  classDef code fill:#d9ead3,stroke:#38761d,color:#1f2326,stroke-width:1px;
  classDef env fill:#cfe2f3,stroke:#1c4587,color:#1f2326,stroke-width:1px;
  classDef tool fill:#ffd966,stroke:#7f6000,color:#1f2326,stroke-width:1px;
  classDef llm fill:#d9d2e9,stroke:#674ea7,color:#1f2326,stroke-width:1px;
  classDef control fill:#f8cbad,stroke:#7f6000,color:#1f2326,stroke-width:1px;
  classDef human fill:#ffffff,stroke:#333333,color:#111111,stroke-width:1px;
  classDef folder fill:#9fc5e8,stroke:#1c4587,color:#1f2326,stroke-width:1px;
  classDef decision fill:#fff2cc,stroke:#7f6000,color:#1f2326,stroke-width:1px;
```
