# iyadeh/ctf-methodology-trainer architecture

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

- Interactive diagram: https://gitdiagram.com/iyadeh/ctf-methodology-trainer
- Repository: https://github.com/iyadeh/ctf-methodology-trainer

## Overview

CTF Methodology Trainer is a local-first app for turning machine writeups into hidden knowledge and guiding evidence-driven penetration-testing practice. The intended learner flow is writeup upload and knowledge preparation, then a PTES-adapted training session with phase/check progression, findings, hypotheses, attempts, and contextual evidence. The README says UI and local database infrastructure exist, but domain persistence is not implemented; sampled screens include demo data and generation-preview fixtures, not a functioning generation pipeline. The graph therefore separates documented capabilities from the implemented training/context services; unsampled UI wiring is not inferred.

Main entry points: [`src/lib/db/index.ts`](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/lib/db/index.ts) (Database client), [`src/modules/context/service.ts`](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/service.ts) (Context reconciliation), [`src/components/layout/app-shell.tsx`](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/layout/app-shell.tsx) (App shell), [`src/modules/training/repository.ts`](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/repository.ts) (Session persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_product_ui["Product UI"]
  node_app_shell["App shell<br/>[app-shell.tsx]"]
  node_dashboard["Training dashboard<br/>[dashboard.tsx]"]
  node_training_pages["Training pages"]
  node_writeup_upload["Writeup upload<br/>[writeup-upload.tsx]"]
  node_generation_preview["Generation preview"]
  node_session_browser["Session browser"]
  node_methodology_page["Methodology reference<br/>[page.tsx]"]
  node_knowledge_page["Knowledge view<br/>[page.tsx]"]
end

subgraph group_training_runtime["Training runtime"]
  node_training_service["Session orchestration<br/>[service.ts]"]
  node_training_repository["Session persistence<br/>[repository.ts]"]
  node_methodology_engine["PTES progression rules<br/>[engine.ts]"]
  node_ptes_framework["PTES checks<br/>[ptes.ts]"]
end

subgraph group_context_evidence["Evidence and context"]
  node_evidence_input["Evidence validation<br/>[evidence-input.ts]"]
  node_evidence_service["Evidence handling<br/>[evidence.ts]"]
  node_evidence_repository["Findings and attempts"]
  node_context_service["Context reconciliation<br/>[service.ts]"]
  node_context_engine["Context normalization<br/>[engine.ts]"]
  node_context_repository["Session context<br/>[repository.ts]"]
end

subgraph group_local_infrastructure["Local data infrastructure"]
  node_db_client["Database client<br/>[index.ts]"]
  node_schema["Domain schema<br/>[schema.ts]"]
end

node_learner(("Learner"))
node_postgres[("PostgreSQL")]
node_hidden_knowledge["Hidden machine knowledge"]

node_learner -->|"uses"| node_app_shell
node_app_shell -->|"presents"| node_dashboard
node_app_shell -->|"navigates"| node_training_pages
node_learner -->|"selects writeup"| node_writeup_upload
node_writeup_upload -->|"previews states"| node_generation_preview
node_learner -->|"browses sessions"| node_session_browser
node_learner -->|"reads"| node_methodology_page
node_learner -->|"views knowledge"| node_knowledge_page
node_training_service -->|"loads and updates"| node_training_repository
node_training_service -->|"evaluates progress"| node_methodology_engine
node_methodology_engine -->|"uses checks"| node_ptes_framework
node_training_repository -->|"loads context"| node_context_repository
node_training_repository -->|"queries"| node_db_client
node_evidence_service -->|"validates input"| node_evidence_input
node_evidence_service -->|"reads and writes"| node_evidence_repository
node_context_service -->|"locks findings"| node_evidence_repository
node_context_service -->|"derives keys"| node_context_engine
node_context_service -->|"reconciles context"| node_context_repository
node_context_repository -->|"queries and updates"| node_db_client
node_db_client -->|"connects"| node_postgres
node_schema -->|"defines tables"| node_db_client
node_hidden_knowledge -.->|"source writeup"| node_writeup_upload

click node_app_shell "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/layout/app-shell.tsx"
click node_dashboard "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/dashboard/dashboard.tsx"
click node_training_pages "https://github.com/iyadeh/ctf-methodology-trainer/tree/main/src/app/training"
click node_writeup_upload "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/training/writeup-upload.tsx"
click node_generation_preview "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/training/generation-preview.tsx"
click node_session_browser "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/training/training-session-browser.tsx"
click node_methodology_page "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/app/methodology/page.tsx"
click node_knowledge_page "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/app/knowledge/page.tsx"
click node_training_service "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/service.ts"
click node_training_repository "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/repository.ts"
click node_methodology_engine "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/methodology/engine.ts"
click node_ptes_framework "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/methodology/ptes.ts"
click node_evidence_input "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/evidence-input.ts"
click node_evidence_service "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/evidence.ts"
click node_evidence_repository "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/evidence-repository.ts"
click node_context_service "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/service.ts"
click node_context_engine "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/engine.ts"
click node_context_repository "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/repository.ts"
click node_db_client "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/lib/db/index.ts"
click node_schema "https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/lib/db/schema.ts"

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_app_shell,node_dashboard,node_training_pages,node_writeup_upload,node_generation_preview,node_session_browser,node_methodology_page,node_knowledge_page toneBlue
class node_training_service,node_training_repository,node_methodology_engine,node_ptes_framework,node_postgres toneAmber
class node_evidence_input,node_evidence_service,node_evidence_repository,node_context_service,node_context_engine,node_context_repository toneMint
class node_db_client,node_schema toneRose
class node_learner,node_hidden_knowledge toneIndigo
```

## Components

### Product UI

- [App shell](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/layout/app-shell.tsx): `src/components/layout/app-shell.tsx`
- [Training dashboard](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/dashboard/dashboard.tsx): `src/components/dashboard/dashboard.tsx`
- [Training pages](https://github.com/iyadeh/ctf-methodology-trainer/tree/main/src/app/training): `src/app/training`
- [Writeup upload](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/training/writeup-upload.tsx): `src/components/training/writeup-upload.tsx`
- [Generation preview](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/training/generation-preview.tsx): `src/components/training/generation-preview.tsx`
- [Session browser](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/components/training/training-session-browser.tsx): `src/components/training/training-session-browser.tsx`
- [Methodology reference](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/app/methodology/page.tsx): `src/app/methodology/page.tsx`
- [Knowledge view](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/app/knowledge/page.tsx): `src/app/knowledge/page.tsx`

### Training runtime

- [Session orchestration](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/service.ts): `src/modules/training/service.ts`
- [Session persistence](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/repository.ts): `src/modules/training/repository.ts`
- [PTES progression rules](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/methodology/engine.ts): `src/modules/methodology/engine.ts`
- [PTES checks](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/methodology/ptes.ts): `src/modules/methodology/ptes.ts`

### Evidence and context

- [Evidence validation](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/evidence-input.ts): `src/modules/training/evidence-input.ts`
- [Evidence handling](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/evidence.ts): `src/modules/training/evidence.ts`
- [Findings and attempts](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/training/evidence-repository.ts): `src/modules/training/evidence-repository.ts`
- [Context reconciliation](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/service.ts): `src/modules/context/service.ts`
- [Context normalization](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/engine.ts): `src/modules/context/engine.ts`
- [Session context](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/modules/context/repository.ts): `src/modules/context/repository.ts`

### Local data infrastructure

- [Database client](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/lib/db/index.ts): `src/lib/db/index.ts`
- [Domain schema](https://github.com/iyadeh/ctf-methodology-trainer/blob/main/src/lib/db/schema.ts): `src/lib/db/schema.ts`

### Other components

- **Learner**
- **PostgreSQL**
- **Hidden machine knowledge**

## Connections

- Learner → App shell: uses
- App shell → Training dashboard: presents
- App shell → Training pages: navigates
- Learner → Writeup upload: selects writeup
- Writeup upload → Generation preview: previews states
- Learner → Session browser: browses sessions
- Learner → Methodology reference: reads
- Learner → Knowledge view: views knowledge
- Session orchestration → Session persistence: loads and updates
- Session orchestration → PTES progression rules: evaluates progress
- PTES progression rules → PTES checks: uses checks
- Session persistence → Session context: loads context
- Session persistence → Database client: queries
- Evidence handling → Evidence validation: validates input
- Evidence handling → Findings and attempts: reads and writes
- Context reconciliation → Findings and attempts: locks findings
- Context reconciliation → Context normalization: derives keys
- Context reconciliation → Session context: reconciles context
- Session context → Database client: queries and updates
- Database client → PostgreSQL: connects
- Domain schema → Database client: defines tables
- Hidden machine knowledge → Writeup upload: source writeup