# johnandrewbalbarosa/neoterritory architecture

> Architecture diagram of the GitHub repository johnandrewbalbarosa/neoterritory, 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/johnandrewbalbarosa/neoterritory
- Repository: https://github.com/johnandrewbalbarosa/neoterritory

## Overview

NeoTerritory is a research-oriented learning product whose central workflow analyzes submitted C++ projects for design-pattern evidence and presents source-anchored educational reports. The documented analyzer stages run from source reading through tree construction, pattern dispatch, evidence linking, and report generation. Separate learning and administration branches provide assessments, readiness decisions, saved-run review, and operational controls. The README describes the service boundaries and the C++ pipeline contract declares its stages; sampled excerpts do not establish every runtime connection between them.

Main entry points: [`Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp`](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp) (Pipeline contract), [`Codebase/Backend/src/controllers/projectLearningOrchestrationController.ts`](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/controllers/projectLearningOrchestrationController.ts) (Learning controller), [`Codebase/Frontend/src/api/client.ts`](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/api/client.ts) (Frontend API client), [`Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/algorithm_pipeline.hpp`](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/algorithm_pipeline.hpp) (Analysis report)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_analysis["C++ Analysis"]
  node_analyzer["Pipeline contract<br/>[pipeline_state.hpp]"]
  node_source_analysis["Read source<br/>[source_reader.hpp]"]
  node_tree_stage["Build trees<br/>[pipeline_state.hpp]"]
  node_pattern_dispatch["Match patterns<br/>[matcher.hpp]"]
  node_evidence_links["Link evidence"]
  node_report["Analysis report"]
end

subgraph group_api["API Services"]
  node_backend["Backend API<br/>[server.ts]"]
  node_transform_routes["Transform routes<br/>[transform.ts]"]
  node_transform_controller["Transform controller"]
end

subgraph group_learning["Learning"]
  node_orchestration_routes["Project learning routes"]
  node_orchestration_controller["Learning controller"]
  node_intake["Project brief intake"]
  node_toggle_policy["Feature toggle policy"]
  node_assessment["Assessment scoring"]
  node_readiness["Readiness evidence"]
end

subgraph group_interface["User Interfaces"]
  node_studio["Studio submission<br/>[StudioApp.tsx]"]
  node_api_client["Frontend API client<br/>[client.ts]"]
  node_report_ui["Annotated results<br/>[SourceView.tsx]"]
  node_learning_ui["Learning assessments"]
  node_admin_ui["Admin console<br/>[AdminApp.tsx]"]
  node_runs_ui["Saved run controls<br/>[RunsManager.tsx]"]
end

node_student(("Student or researcher"))

node_student -->|"submits C++"| node_studio
node_studio -->|"sends request"| node_api_client
node_api_client -->|"calls API"| node_backend
node_backend -->|"dispatches"| node_transform_routes
node_transform_routes -->|"routes to"| node_transform_controller
node_transform_controller -.->|"invokes analysis"| node_analyzer
node_analyzer -->|"runs stage"| node_source_analysis
node_analyzer -->|"runs stage"| node_tree_stage
node_analyzer -->|"runs stage"| node_pattern_dispatch
node_analyzer -->|"runs stage"| node_evidence_links
node_analyzer -->|"generates"| node_report
node_report -.->|"returns findings"| node_report_ui
node_student -->|"takes assessments"| node_learning_ui
node_learning_ui -->|"submits attempt"| node_orchestration_routes
node_orchestration_routes -->|"routes to"| node_orchestration_controller
node_orchestration_controller -->|"intakes brief"| node_intake
node_orchestration_controller -->|"resolves toggles"| node_toggle_policy
node_orchestration_controller -->|"scores attempt"| node_assessment
node_orchestration_controller -->|"checks readiness"| node_readiness
node_admin_ui -->|"calls API"| node_api_client
node_runs_ui -->|"loads and manages runs"| node_api_client

click node_studio "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/components/studio/StudioApp.tsx"
click node_api_client "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/api/client.ts"
click node_backend "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/server.ts"
click node_transform_routes "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/routes/transform.ts"
click node_transform_controller "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/controllers/transformController.ts"
click node_analyzer "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp"
click node_source_analysis "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/Analysis/Input/source_reader.hpp"
click node_tree_stage "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp"
click node_pattern_dispatch "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/Analysis/Patterns/Catalog/matcher.hpp"
click node_evidence_links "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/HashingMechanism/HashLinks/Flow/parse_tree_hash_links_program_flow.hpp"
click node_report "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/algorithm_pipeline.hpp"
click node_report_ui "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/components/analysis/SourceView.tsx"
click node_learning_ui "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/components/learn/LearningAssessmentPage.tsx"
click node_orchestration_routes "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/routes/projectLearningOrchestration.ts"
click node_orchestration_controller "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/controllers/projectLearningOrchestrationController.ts"
click node_intake "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/projectSpecIntakeService.ts"
click node_toggle_policy "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/featureTogglePolicyService.ts"
click node_assessment "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/assessmentOrchestrationService.ts"
click node_readiness "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/readinessEvidenceService.ts"
click node_admin_ui "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/admin/AdminApp.tsx"
click node_runs_ui "https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/admin/components/RunsManager.tsx"

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_analyzer,node_source_analysis,node_tree_stage,node_pattern_dispatch,node_evidence_links,node_report toneBlue
class node_backend,node_transform_routes,node_transform_controller toneAmber
class node_orchestration_routes,node_orchestration_controller,node_intake,node_toggle_policy,node_assessment,node_readiness toneMint
class node_studio,node_api_client,node_report_ui,node_learning_ui,node_admin_ui,node_runs_ui toneRose
class node_student toneIndigo
```

## Components

### C++ Analysis

- [Pipeline contract](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp): `Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp`
- [Read source](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/Analysis/Input/source_reader.hpp): `Codebase/Microservice/Modules/Header/Analysis/Input/source_reader.hpp`
- [Build trees](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp): `Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/pipeline_state.hpp`
- [Match patterns](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/Analysis/Patterns/Catalog/matcher.hpp): `Codebase/Microservice/Modules/Header/Analysis/Patterns/Catalog/matcher.hpp`
- [Link evidence](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/HashingMechanism/HashLinks/Flow/parse_tree_hash_links_program_flow.hpp): `Codebase/Microservice/Modules/Header/HashingMechanism/HashLinks/Flow/parse_tree_hash_links_program_flow.hpp`
- [Analysis report](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/algorithm_pipeline.hpp): `Codebase/Microservice/Modules/Header/OutputGeneration/Contracts/algorithm_pipeline.hpp`

### API Services

- [Backend API](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/server.ts): `Codebase/Backend/server.ts`
- [Transform routes](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/routes/transform.ts): `Codebase/Backend/src/routes/transform.ts`
- [Transform controller](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/controllers/transformController.ts): `Codebase/Backend/src/controllers/transformController.ts`

### Learning

- [Project learning routes](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/routes/projectLearningOrchestration.ts): `Codebase/Backend/src/routes/projectLearningOrchestration.ts`
- [Learning controller](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/controllers/projectLearningOrchestrationController.ts): `Codebase/Backend/src/controllers/projectLearningOrchestrationController.ts`
- [Project brief intake](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/projectSpecIntakeService.ts): `Codebase/Backend/src/services/projectSpecIntakeService.ts`
- [Feature toggle policy](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/featureTogglePolicyService.ts): `Codebase/Backend/src/services/featureTogglePolicyService.ts`
- [Assessment scoring](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/assessmentOrchestrationService.ts): `Codebase/Backend/src/services/assessmentOrchestrationService.ts`
- [Readiness evidence](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Backend/src/services/readinessEvidenceService.ts): `Codebase/Backend/src/services/readinessEvidenceService.ts`

### User Interfaces

- [Studio submission](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/components/studio/StudioApp.tsx): `Codebase/Frontend/src/components/studio/StudioApp.tsx`
- [Frontend API client](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/api/client.ts): `Codebase/Frontend/src/api/client.ts`
- [Annotated results](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/components/analysis/SourceView.tsx): `Codebase/Frontend/src/components/analysis/SourceView.tsx`
- [Learning assessments](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/components/learn/LearningAssessmentPage.tsx): `Codebase/Frontend/src/components/learn/LearningAssessmentPage.tsx`
- [Admin console](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/admin/AdminApp.tsx): `Codebase/Frontend/src/admin/AdminApp.tsx`
- [Saved run controls](https://github.com/johnandrewbalbarosa/neoterritory/blob/main/Codebase/Frontend/src/admin/components/RunsManager.tsx): `Codebase/Frontend/src/admin/components/RunsManager.tsx`

### Other components

- **Student or researcher**

## Connections

- Student or researcher → Studio submission: submits C++
- Studio submission → Frontend API client: sends request
- Frontend API client → Backend API: calls API
- Backend API → Transform routes: dispatches
- Transform routes → Transform controller: routes to
- Transform controller → Pipeline contract: invokes analysis
- Pipeline contract → Read source: runs stage
- Pipeline contract → Build trees: runs stage
- Pipeline contract → Match patterns: runs stage
- Pipeline contract → Link evidence: runs stage
- Pipeline contract → Analysis report: generates
- Analysis report → Annotated results: returns findings
- Student or researcher → Learning assessments: takes assessments
- Learning assessments → Project learning routes: submits attempt
- Project learning routes → Learning controller: routes to
- Learning controller → Project brief intake: intakes brief
- Learning controller → Feature toggle policy: resolves toggles
- Learning controller → Assessment scoring: scores attempt
- Learning controller → Readiness evidence: checks readiness
- Admin console → Frontend API client: calls API
- Saved run controls → Frontend API client: loads and manages runs