# edward-playground/aidefense-framework architecture

> Architecture diagram of the GitHub repository edward-playground/aidefense-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/edward-playground/aidefense-framework
- Repository: https://github.com/edward-playground/aidefense-framework

## Overview

#### Purpose and delivery model
AIDEFEND is a static, browser-delivered knowledge base of actionable AI-defense controls, organized for exploration and machine consumption. The main application starts at `index.html`, with client behavior in `main.js`; no application server or package-installed runtime is required. A separate simplified experience starts at `kids.html` and `kids/kids-main.js`.

#### Authoritative framework content
The seven tactic modules are the authored source of truth, partitioning controls by security function: `tactics/model.js`, `tactics/harden.js`, `tactics/detect.js`, `tactics/isolate.js`, `tactics/deceive.js`, `tactics/evict.js`, and `tactics/restore.js`. They define the control hierarchy, guidance, scope boundaries, and external-framework mappings. Parent families are navigational aggregations; actionable standalone and leaf controls are the assessment unit.

#### Dataset build boundary
Node.js generation converts authored tactic modules into public, intentionally reduced datasets. `scripts/generate-dataset.js` validates hierarchy and keyword constraints, then writes `data/data.json` and `data/tactics-index.json`; source-only guidance and warning fields are excluded by design. `data/framework-migrations.json` is an additive registry for framework editions and semantic successors, not a mechanism to inherit mappings.

#### Main browser application
`main.js` loads local framework data and drives the Tactics, Pillars, Phases, and Frameworks views. `js/atlas-matrix-navigation.js` provides ATLAS-oriented navigation behavior. Presentation is static HTML/CSS with local browser dependencies under `css/main.css`, `css/themes.css`, and `js/tailwindcss.js`; all primary browsing remains functional without optional third parties.

#### External-framework integration
The Frameworks view performs reverse lookup from external threats or risks to AIDEFEND controls. Cisco v2 taxonomy and provenance are represented by `cisco-framework.js`, transformed/publicly available as `data/cisco-framework.json`. Migration resolution logic is isolated in `framework-migrations.js`, preserving edition boundaries and rejecting ambiguous, retired, or unsupported identifiers rather than silently remapping them.

#### Optional programmatic browser access
`webmcp-tools.js` registers read-only lookup tools only if the browser exposes `document.modelContext.registerTool`; `webmcp-query.js` implements query/resolution behavior. The optional runtime is loaded from unpkg with a pinned integrity hash, while compatible native browser implementations bypass it. Its absence must not affect normal data browsing or public JSON use.

#### Release and operational controls
The project runs as static assets under any HTTP server; external requests are limited to hosted fonts, Google Analytics, and optional WebMCP runtime. Release automation in `.github/workflows/release-tag.yml` validates generated outputs and creates immutable annotated version tags from `main`. Version/tag policy is implemented by `scripts/release-tag.mjs`; generated content and version metadata must be committed together.

Main entry points: [`main.js`](https://github.com/edward-playground/aidefense-framework/blob/main/main.js) (Main application), [`scripts/generate-dataset.js`](https://github.com/edward-playground/aidefense-framework/blob/main/scripts/generate-dataset.js) (Dataset generator), [`data/data.json`](https://github.com/edward-playground/aidefense-framework/blob/main/data/data.json) (Public controls dataset), [`webmcp-tools.js`](https://github.com/edward-playground/aidefense-framework/blob/main/webmcp-tools.js) (WebMCP tool registration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Framework authoring"]
  node_tactic_modules["Seven tactic modules<br/>authored controls"]
  node_migration_registry["Migration registry<br/>edition registry"]
end

subgraph group_build["Dataset build"]
  node_dataset_generator{{"Dataset generator<br/>Node.js build script"}}
  node_public_dataset["Public controls dataset<br/>generated JSON<br/>[data.json]"]
  node_tactics_index["Tactics index<br/>generated JSON<br/>[tactics-index.json]"]
end

subgraph group_browser["Static browser app"]
  node_main_entry["Main entry<br/>static HTML<br/>[index.html]"]
  node_main_app{{"Main application<br/>browser controller<br/>[main.js]"}}
  node_atlas_navigation["ATLAS navigation<br/>browser behavior"]
  node_presentation["Static presentation<br/>local CSS and JS"]
  node_kids_entry["Kids entry<br/>static HTML<br/>[kids.html]"]
  node_kids_app["Kids application<br/>browser controller<br/>[kids-main.js]"]
end

subgraph group_integration["Framework integration"]
  node_cisco_source["Cisco v2 taxonomy<br/>framework source<br/>[cisco-framework.js]"]
  node_cisco_dataset["Cisco public dataset<br/>framework JSON"]
  node_migration_resolver{{"Migration resolver<br/>resolution logic"}}
  node_webmcp_tools["WebMCP tool registration<br/>optional browser integration<br/>[webmcp-tools.js]"]
  node_webmcp_query["WebMCP query engine<br/>query logic<br/>[webmcp-query.js]"]
end

subgraph group_release["Release controls"]
  node_release_workflow{{"Release workflow<br/>GitHub Actions workflow<br/>[release-tag.yml]"}}
  node_release_policy["Version/tag policy<br/>release script<br/>[release-tag.mjs]"]
end

node_tactic_modules -->|"validates and reduces"| node_dataset_generator
node_dataset_generator -->|"writes"| node_public_dataset
node_dataset_generator -->|"writes"| node_tactics_index
node_main_entry -->|"loads"| node_main_app
node_main_app -->|"loads"| node_public_dataset
node_main_app -->|"loads"| node_tactics_index
node_main_app -->|"uses"| node_atlas_navigation
node_presentation -->|"presents"| node_main_entry
node_kids_entry -->|"loads"| node_kids_app
node_cisco_source -->|"published as"| node_cisco_dataset
node_main_app -->|"reverse lookup"| node_cisco_dataset
node_main_app -->|"resolves editions"| node_migration_resolver
node_migration_registry -->|"supplies successors"| node_migration_resolver
node_webmcp_tools -->|"registers"| node_webmcp_query
node_webmcp_query -->|"queries"| node_public_dataset
node_webmcp_tools -.->|"optional alongside"| node_main_app
node_release_workflow -->|"validates outputs"| node_dataset_generator
node_release_workflow -->|"applies"| node_release_policy

click node_migration_registry "https://github.com/edward-playground/aidefense-framework/blob/main/data/framework-migrations.json"
click node_dataset_generator "https://github.com/edward-playground/aidefense-framework/blob/main/scripts/generate-dataset.js"
click node_public_dataset "https://github.com/edward-playground/aidefense-framework/blob/main/data/data.json"
click node_tactics_index "https://github.com/edward-playground/aidefense-framework/blob/main/data/tactics-index.json"
click node_main_entry "https://github.com/edward-playground/aidefense-framework/blob/main/index.html"
click node_main_app "https://github.com/edward-playground/aidefense-framework/blob/main/main.js"
click node_atlas_navigation "https://github.com/edward-playground/aidefense-framework/blob/main/js/atlas-matrix-navigation.js"
click node_kids_entry "https://github.com/edward-playground/aidefense-framework/blob/main/kids.html"
click node_kids_app "https://github.com/edward-playground/aidefense-framework/blob/main/kids/kids-main.js"
click node_cisco_source "https://github.com/edward-playground/aidefense-framework/blob/main/cisco-framework.js"
click node_cisco_dataset "https://github.com/edward-playground/aidefense-framework/blob/main/data/cisco-framework.json"
click node_migration_resolver "https://github.com/edward-playground/aidefense-framework/blob/main/framework-migrations.js"
click node_webmcp_tools "https://github.com/edward-playground/aidefense-framework/blob/main/webmcp-tools.js"
click node_webmcp_query "https://github.com/edward-playground/aidefense-framework/blob/main/webmcp-query.js"
click node_release_workflow "https://github.com/edward-playground/aidefense-framework/blob/main/.github/workflows/release-tag.yml"
click node_release_policy "https://github.com/edward-playground/aidefense-framework/blob/main/scripts/release-tag.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tactic_modules,node_migration_registry toneBlue
class node_dataset_generator,node_public_dataset,node_tactics_index toneAmber
class node_main_entry,node_main_app,node_atlas_navigation,node_presentation,node_kids_entry,node_kids_app toneMint
class node_cisco_source,node_cisco_dataset,node_migration_resolver,node_webmcp_tools,node_webmcp_query toneRose
class node_release_workflow,node_release_policy toneIndigo
```

## Components

### Framework authoring

- **Seven tactic modules**: authored controls · Authoritative control hierarchy, guidance, boundaries, and mappings.
- [Migration registry](https://github.com/edward-playground/aidefense-framework/blob/main/data/framework-migrations.json): edition registry · Additive edition and semantic-successor registry. · `data/framework-migrations.json`

### Dataset build

- [Dataset generator](https://github.com/edward-playground/aidefense-framework/blob/main/scripts/generate-dataset.js): Node.js build script · Validates authored hierarchy and keywords while reducing public fields. · `scripts/generate-dataset.js`
- [Public controls dataset](https://github.com/edward-playground/aidefense-framework/blob/main/data/data.json): generated JSON · Reduced machine-consumable control data. · `data/data.json`
- [Tactics index](https://github.com/edward-playground/aidefense-framework/blob/main/data/tactics-index.json): generated JSON · `data/tactics-index.json`

### Static browser app

- [Main entry](https://github.com/edward-playground/aidefense-framework/blob/main/index.html): static HTML · `index.html`
- [Main application](https://github.com/edward-playground/aidefense-framework/blob/main/main.js): browser controller · Drives Tactics, Pillars, Phases, and Frameworks views. · `main.js`
- [ATLAS navigation](https://github.com/edward-playground/aidefense-framework/blob/main/js/atlas-matrix-navigation.js): browser behavior · `js/atlas-matrix-navigation.js`
- **Static presentation**: local CSS and JS · Local dependencies keep primary browsing available offline from third parties.
- [Kids entry](https://github.com/edward-playground/aidefense-framework/blob/main/kids.html): static HTML · Separate simplified experience. · `kids.html`
- [Kids application](https://github.com/edward-playground/aidefense-framework/blob/main/kids/kids-main.js): browser controller · `kids/kids-main.js`

### Framework integration

- [Cisco v2 taxonomy](https://github.com/edward-playground/aidefense-framework/blob/main/cisco-framework.js): framework source · Cisco taxonomy and provenance representation. · `cisco-framework.js`
- [Cisco public dataset](https://github.com/edward-playground/aidefense-framework/blob/main/data/cisco-framework.json): framework JSON · `data/cisco-framework.json`
- [Migration resolver](https://github.com/edward-playground/aidefense-framework/blob/main/framework-migrations.js): resolution logic · Rejects ambiguous, retired, and unsupported framework identifiers. · `framework-migrations.js`
- [WebMCP tool registration](https://github.com/edward-playground/aidefense-framework/blob/main/webmcp-tools.js): optional browser integration · Registers read-only tools only when browser support exists. · `webmcp-tools.js`
- [WebMCP query engine](https://github.com/edward-playground/aidefense-framework/blob/main/webmcp-query.js): query logic · `webmcp-query.js`

### Release controls

- [Release workflow](https://github.com/edward-playground/aidefense-framework/blob/main/.github/workflows/release-tag.yml): GitHub Actions workflow · Validates generated outputs and creates immutable annotated tags from main. · `.github/workflows/release-tag.yml`
- [Version/tag policy](https://github.com/edward-playground/aidefense-framework/blob/main/scripts/release-tag.mjs): release script · Requires generated content and version metadata to be committed together. · `scripts/release-tag.mjs`

## Connections

- Seven tactic modules → Dataset generator: validates and reduces
- Dataset generator → Public controls dataset: writes
- Dataset generator → Tactics index: writes
- Main entry → Main application: loads
- Main application → Public controls dataset: loads
- Main application → Tactics index: loads
- Main application → ATLAS navigation: uses
- Static presentation → Main entry: presents
- Kids entry → Kids application: loads
- Cisco v2 taxonomy → Cisco public dataset: published as
- Main application → Cisco public dataset: reverse lookup
- Main application → Migration resolver: resolves editions
- Migration registry → Migration resolver: supplies successors
- WebMCP tool registration → WebMCP query engine: registers
- WebMCP query engine → Public controls dataset: queries
- WebMCP tool registration → Main application: optional alongside
- Release workflow → Dataset generator: validates outputs
- Release workflow → Version/tag policy: applies
