Nexus SecOps AI Architecture¶

Internal documentation -- This document describes the AI systems powering Nexus SecOps. It is included in the repository for transparency and academic review but is not linked from the live site navigation.

Overview¶

Nexus SecOps operates with three interconnected AI layers that work together to build, maintain, and improve the site autonomously:

These layers are not independent. The Brain consumes the Knowledge Graph during its reasoning phases, and GraphRAG uses the graph to ground LLM responses in structured prerequisite relationships.

Knowledge Graph Schema¶

The knowledge graph is stored in docs/learning-graph/graph.json (vis.js compatible) with a CSV interchange format in docs/learning-graph/concepts.csv and docs/learning-graph/dependencies.csv.

Node Schema¶

{
  "id": "C001",
  "label": "CIA Triad",
  "group": "T01",
  "shape": "box",
  "title": "Confidentiality, Integrity, Availability — the foundational security model",
  "url": "chapters/ch01-introduction/"
}

Node Shapes (Concept Types)¶

Edge Schema¶

{
  "from": "C001",
  "to": "C002"
}

Edges are directed: from is a prerequisite of to. This means "you should understand C001 before learning C002."

Taxonomy Categories¶

Graph Validation Rules¶

The knowledge graph enforces 6 structural rules during CI validation:

1. Prerequisite coverage: Every non-foundation node (shape != box) must have at least 1 incoming edge
2. No self-dependencies: No node can list itself as a prerequisite
3. Acyclic: The graph must be a DAG (directed acyclic graph) -- no circular prerequisite chains
4. No orphans: Every node must be reachable from at least one foundation node
5. Fully connected: The graph forms a single connected component (no isolated subgraphs)
6. Category balance: No single taxonomy category may contain more than 30% of all nodes

10-Phase Cognitive Cycle¶

The Nexus Brain executes a 10-phase cognitive cycle on each run. This is implemented in .github/workflows/brain.yml and the supporting Python scripts.

graph LR
    P[PERCEIVE] --> RC[RECALL]
    RC --> A[ANALYZE]
    A --> R[REASON]
    R --> CR[CRITIQUE]
    CR --> RF[REFINE]
    RF --> ACT[ACT]
    ACT --> E[EVALUATE]
    E --> L[LEARN]
    L --> RM[REMEMBER]
    RM -.->|next cycle| P

Phase Descriptions¶

Cycle Scheduling¶

gantt
    title Brain Execution Schedule
    dateFormat  YYYY-MM-DD
    section Weekly Cycles
    Monday Run     :active, mon, 2026-03-30, 1d
    Thursday Run   :active, thu, 2026-04-02, 1d
    Monday Run     :active, mon2, 2026-04-06, 1d
    Thursday Run   :active, thu2, 2026-04-09, 1d

The Brain runs automatically via GitHub Actions on Monday and Thursday mornings. Each run takes 3--5 minutes and produces 1--3 pull requests.

Multi-LLM Router¶

The Brain does not rely on a single LLM. It uses an epsilon-greedy multi-armed bandit algorithm to route requests across four free-tier providers.

Provider Pool¶

Total cost: $0. All providers offer free tiers sufficient for the Brain's twice-weekly execution schedule.

Routing Algorithm¶

flowchart TD
    REQ[New LLM Request] --> RAND{Random < epsilon?}
    RAND -->|Yes: Explore| RANDOM[Pick random provider]
    RAND -->|No: Exploit| BEST[Pick highest-reward provider]
    RANDOM --> CALL[Call LLM API]
    BEST --> CALL
    CALL --> SUCCESS{Success?}
    SUCCESS -->|Yes| REWARD[Update reward: quality score]
    SUCCESS -->|No| FALLBACK[Try next provider in chain]
    FALLBACK --> CALL
    REWARD --> DECAY[Decay epsilon]

• Epsilon starts at 0.3 (30% exploration) and decays toward 0.05 over time
• Rewards are tracked per-phase (a provider good at REASON may not be good at CRITIQUE)
• Fallback chain: Mistral -> Gemini -> Groq -> Cohere. If the selected provider fails, the next in chain is tried automatically
• Performance history is persisted in brain-memory.json across cycles

Self-Monitoring Infrastructure¶

count_validator.py¶

Problem: The site announces content counts in many places (homepage, nav descriptions, chapter headers, CLAUDE.md). When content is added, these counts go stale silently.

Solution: scripts/count_validator.py scans all markdown files for numeric content claims and validates them against actual file counts. Runs in CI on every push.

flowchart LR
    PUSH[Git Push] --> CI[GitHub Actions]
    CI --> CV[count_validator.py]
    CV --> SCAN[Scan .md files for count patterns]
    SCAN --> COUNT[Count actual files in each category]
    COUNT --> COMPARE{Counts match?}
    COMPARE -->|Yes| PASS[CI passes]
    COMPARE -->|No| FAIL[CI fails with specific mismatches]

content_refresh.py¶

Scans all content files and flags anything not updated in the last 90 days. Generates CONTENT_STATUS.md with a freshness report. Used by the Brain's PERCEIVE phase to identify stale content.

PR Validation Workflow¶

Every pull request (both human and Brain-generated) must pass:

1. mkdocs build --strict -- zero warnings, zero errors
2. Broken link check -- all internal links resolve
3. Synthetic data compliance -- no real IPs, credentials, or domains
4. Count validation -- announced numbers match reality

Brain Auto-Merge¶

Brain-generated PRs can be auto-merged after passing 6 quality gates:

1. CI pipeline passes (build + validation)
2. No merge conflicts
3. Content count validation passes
4. All quality gate checks from CRITIQUE phase logged
5. PR description includes reasoning trace
6. No structural changes (nav, config, or schema modifications require human review)

How AI Built This Site¶

Claude Code (Primary Development Tool)¶

Nexus SecOps was built across 17 iterative sessions using Claude Code as the primary development tool. Each session followed a structured protocol:

1. Read NEXT_SESSION.md for priorities
2. Run mkdocs build --strict to establish baseline
3. Execute prioritized tasks (content creation, tooling, infrastructure)
4. Update all state files (CLAUDE.md, NEXT_SESSION.md, EVOLUTION_LOG.md)
5. Commit and push

Claude Code wrote all 50 chapters, 40 MicroSims, 26 labs, the gamification system, the knowledge graph, the Brain infrastructure, CI/CD pipelines, and the custom theme.

Nexus Brain (Autonomous Maintenance)¶

Between human sessions, the Brain runs autonomously to:

• Generate threat intelligence blog posts from real feed data
• Create new detection rules (KQL and SPL)
• Update stale content with current references
• Expand the knowledge graph with new concepts
• File issues for gaps it cannot fix autonomously

Graph-Aware Reasoning¶

The Brain's key differentiator is that it reasons about content structurally, not just textually. When the ANALYZE phase identifies that concept C245 (Cloud Container Security) has weak coverage, it doesn't just flag the gap. It traverses the prerequisite chain:

C001 (CIA Triad) -> C042 (Cloud Fundamentals) -> C178 (Container Basics) -> C245 (Cloud Container Security)

This prerequisite chain is injected into the REASON phase prompt, so the LLM understands not just what to write, but where it fits in the learning progression and what concepts it should reference.

Architecture Diagram¶

flowchart TB
    subgraph "Human Layer"
        CC[Claude Code Sessions]
        HR[Human Review]
    end
    subgraph "AI Layer"
        BRAIN[Nexus Brain]
        ROUTER[Multi-LLM Router]
        GRAPH[Knowledge Graph]
    end
    subgraph "Infrastructure"
        GHA[GitHub Actions]
        CF[Cloudflare Pages]
        CI[CI Pipeline]
    end

    CC -->|commits| GHA
    BRAIN -->|PRs| GHA
    GHA -->|build| CI
    CI -->|deploy| CF
    BRAIN --> ROUTER
    ROUTER -->|Mistral/Gemini/Groq/Cohere| BRAIN
    BRAIN -->|reads| GRAPH
    BRAIN -->|expands| GRAPH
    HR -->|merge/reject| GHA

Technical References¶