# lennartkoepper/concept-mapper architecture

> Architecture diagram of the GitHub repository lennartkoepper/concept-mapper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lennartkoepper/concept-mapper
- Repository: https://github.com/lennartkoepper/concept-mapper

## Overview

1. **Overall shape**
   - This repo is a two-tier application: an **Angular frontend** in `cm-frontend` and a **Python backend** in `cm-backend`.
   - The backend is the orchestration and processing layer; the frontend is a thin interactive client for choosing input, configuring generation, and displaying results.

2. **User interaction boundary**
   - The frontend exposes the user-facing workflow through separate UI pieces for **file upload**, **raw text**, **URL input**, and **generation options**.
   - `src/app/_services/api.service.ts` is the main boundary between browser UI and backend API calls.
   - `src/app/_shared/payload.ts` and `options.ts` indicate a structured request/response contract for concept-map generation settings and payloads.

3. **Backend entrypoint and API boundary**
   - `cm-backend/concept_mapper_api.py` is the backend entrypoint and likely the FastAPI application.
   - It sits at the center of the backend, receiving requests from the Angular app and coordinating text ingestion, LLM calls, graph building, visualization, and evaluation.

4. **Input acquisition subsystem**
   - Text can enter the system in three ways: **direct text**, **uploaded files**, or **URLs**.
   - `scrape/simple_text_scraper.py` handles web/content extraction for URL or document-like inputs.
   - `build_cm_from_txt.py` suggests a command-line or utility path for generating concept maps directly from text outside the web UI.

5. **LLM orchestration subsystem**
   - The core extraction logic is in `cm-backend/llm` and `cm-backend/prompts`.
   - `llm/models.py` likely defines the structured schemas used to represent extracted concepts, relations, and map metadata.
   - `prompts/concept_extraction.py`, `summarization.py`, `one_shot_prompts.py`, and `examples.py` show a prompt-driven pipeline: summarize first, then extract structured concept-map data.
   - The README confirms support for **OpenAI** and **Mistral** APIs, configured via environment variables.

6. **Concept-map generation flow**
   - The backend follows a multi-step sequence: ingest text, summarize it, extract concepts/relations, then normalize into a graph-ready structure.
   - The “number of nodes,” temperature, and context preset options affect the LLM prompts and output shape rather than the UI alone.
   - This is a clear boundary: the system is not just generating text, but converting unstructured text into a graph model.

7. **Graph visualization subsystem**
   - `visualize/graphviz_builder.py` is responsible for turning the structured concept map into Graphviz-compatible output.
   - The README indicates export/rendering to multiple formats such as **PDF, PNG, SVG**, so the visualization layer is also the output-format boundary.
   - Generated artifacts are likely stored temporarily under a configurable output directory (`CM_OUT_DIR`).

8. **Evaluation subsystem**
   - `evaluate/graph_evaluator.py` provides graph-based metrics for assessing generated concept maps.
   - This is a separate concern from generation and rendering, so it acts as an analysis layer over the produced graph rather than part of the generation path.
   - The evaluation module likely consumes the same structured graph model used by visualization.

9. **Frontend structure**
   - The Angular app is organized by workflow screens/components:
     - `text-uploader` for pasted text,
     - `file-upload` for document upload,
     - `url-provider` for web-source input,
     - `options` for model/configuration selection.
   - `app.component.*` and `app.routes.ts` tie these pieces together into the main flow.

10. **Deployment model**
   - The repository is designed for both local development and containerized deployment.
   - `docker-compose.yml` coordinates separate frontend and backend containers.
   - The frontend has its own `Dockerfile` and Nginx config, indicating it is served as a static SPA behind a web server.
   - The backend also has a `Dockerfile`, and the project includes both `requirements.txt` and `environment.yml`, reflecting Python dependency management for different runtime paths.

11. **External services and runtime dependencies**
   - The architecture depends on external **LLM providers** rather than local model inference.
   - `OPENAI_API_KEY` and `MISTRAL_API_KEY` are required runtime integration points.
   - Graphviz is a functional dependency for rendering, not just a development tool.

12. **What to draw in an architecture diagram**
   - Draw the frontend as the user entry layer with three input modes plus configuration.
   - Show the backend API as the orchestration hub.
   - From backend, branch to:
     - input extraction/scraping,
     - LLM prompt/model processing,
     - graph construction and Graphviz rendering,
     - evaluation metrics.
   - Add external boundaries for OpenAI/Mistral and Graphviz output generation, plus a temporary output store for generated files.

Main entry points: [`cm-backend/concept_mapper_api.py`](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/concept_mapper_api.py) (API entry), [`cm-backend/visualize/graphviz_builder.py`](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/visualize/graphviz_builder.py) (Graph builder), [`cm-backend/prompts/concept_extraction.py`](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/prompts/concept_extraction.py) (Prompts), [`cm-frontend/src/app/_shared/payload.ts`](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_shared/payload.ts) (Payload)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Angular UI"]
  node_cm_frontend_shell["App shell<br/>[app.component.ts]"]
  node_cm_frontend_routes["Routes<br/>Angular routing<br/>[app.routes.ts]"]
  node_cm_frontend_api["API client<br/>HTTP service<br/>[api.service.ts]"]
  node_cm_frontend_payload["Payload<br/>request models<br/>[payload.ts]"]
  node_cm_frontend_options["Options model<br/>UI config models<br/>[options.ts]"]
  node_cm_frontend_text["Text input<br/>paste uploader"]
  node_cm_frontend_file["File upload"]
  node_cm_frontend_url["URL input<br/>url provider"]
  node_cm_frontend_cfg["Options UI<br/>generation config"]
end

subgraph group_backend["Python backend"]
  node_cm_backend_api["API entry<br/>FastAPI app"]
  node_cm_backend_scrape["Scraper<br/>input extraction"]
  node_cm_backend_build["CLI build<br/>text-to-map utility"]
  node_cm_backend_prompts["Prompts<br/>prompt templates"]
  node_cm_backend_llm["LLM schema<br/>structured models<br/>[models.py]"]
  node_cm_backend_graph["Graph builder<br/>visualization builder"]
  node_cm_backend_eval["Evaluator<br/>graph metrics<br/>[graph_evaluator.py]"]
end

subgraph group_external["External systems"]
  node_ext_llm(("LLM APIs<br/>OpenAI/Mistral"))
  node_ext_graphviz(("Graphviz<br/>rendering dependency"))
end

node_cm_frontend_shell -->|"uses"| node_cm_frontend_routes
node_cm_frontend_shell -->|"calls"| node_cm_frontend_api
node_cm_frontend_text -->|"fills"| node_cm_frontend_payload
node_cm_frontend_file -->|"fills"| node_cm_frontend_payload
node_cm_frontend_url -->|"fills"| node_cm_frontend_payload
node_cm_frontend_cfg -->|"edits"| node_cm_frontend_options
node_cm_frontend_api -->|"requests"| node_cm_backend_api
node_cm_backend_api -->|"ingests"| node_cm_backend_scrape
node_cm_backend_api -->|"prompts"| node_cm_backend_prompts
node_cm_backend_api -->|"structures"| node_cm_backend_llm
node_cm_backend_api -->|"renders"| node_cm_backend_graph
node_cm_backend_api -->|"evaluates"| node_cm_backend_eval
node_cm_backend_build -->|"reuses"| node_cm_backend_scrape
node_cm_backend_build -->|"reuses"| node_cm_backend_prompts
node_cm_backend_prompts -->|"calls"| node_ext_llm
node_cm_backend_llm -.->|"validated by"| node_ext_llm
node_cm_backend_graph -->|"targets"| node_ext_graphviz
node_cm_backend_graph -.->|"shares model"| node_cm_backend_eval

click node_cm_frontend_shell "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/app.component.ts"
click node_cm_frontend_routes "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/app.routes.ts"
click node_cm_frontend_api "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_services/api.service.ts"
click node_cm_frontend_payload "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_shared/payload.ts"
click node_cm_frontend_options "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_shared/options.ts"
click node_cm_frontend_text "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/text-uploader/text-uploader.component.ts"
click node_cm_frontend_file "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/file-upload/file-upload.component.ts"
click node_cm_frontend_url "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/url-provider/url-provider.component.ts"
click node_cm_frontend_cfg "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/options/options.component.ts"
click node_cm_backend_api "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/concept_mapper_api.py"
click node_cm_backend_scrape "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/scrape/simple_text_scraper.py"
click node_cm_backend_build "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/build_cm_from_txt.py"
click node_cm_backend_prompts "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/prompts/concept_extraction.py"
click node_cm_backend_llm "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/llm/models.py"
click node_cm_backend_graph "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/visualize/graphviz_builder.py"
click node_cm_backend_eval "https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/evaluate/graph_evaluator.py"

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_cm_frontend_shell,node_cm_frontend_routes,node_cm_frontend_api,node_cm_frontend_payload,node_cm_frontend_options,node_cm_frontend_text,node_cm_frontend_file,node_cm_frontend_url,node_cm_frontend_cfg toneBlue
class node_cm_backend_api,node_cm_backend_scrape,node_cm_backend_build,node_cm_backend_prompts,node_cm_backend_llm,node_cm_backend_graph,node_cm_backend_eval toneAmber
class node_ext_llm,node_ext_graphviz toneMint
```

## Components

### Angular UI

Browser client for input, options, and result display

- [App shell](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/app.component.ts): Angular app shell · Routes and top-level UI composition · `cm-frontend/src/app/app.component.ts`
- [Routes](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/app.routes.ts): Angular routing · Navigation and screen wiring · `cm-frontend/src/app/app.routes.ts`
- [API client](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_services/api.service.ts): HTTP service · Browser-to-backend request boundary · `cm-frontend/src/app/_services/api.service.ts`
- [Payload](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_shared/payload.ts): request models · Structured generation request/response contract · `cm-frontend/src/app/_shared/payload.ts`
- [Options model](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/_shared/options.ts): UI config models · Generation settings used by the UI · `cm-frontend/src/app/_shared/options.ts`
- [Text input](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/text-uploader/text-uploader.component.ts): paste uploader · Direct text entry workflow · `cm-frontend/src/app/text-uploader/text-uploader.component.ts`
- [File upload](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/file-upload/file-upload.component.ts): file uploader · Document upload workflow · `cm-frontend/src/app/file-upload/file-upload.component.ts`
- [URL input](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/url-provider/url-provider.component.ts): url provider · Web-source input workflow · `cm-frontend/src/app/url-provider/url-provider.component.ts`
- [Options UI](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-frontend/src/app/options/options.component.ts): generation config · Model, size, and prompt options · `cm-frontend/src/app/options/options.component.ts`

### Python backend

API, ingestion, generation, rendering, and evaluation

- [API entry](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/concept_mapper_api.py): FastAPI app · Backend request orchestrator · `cm-backend/concept_mapper_api.py`
- [Scraper](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/scrape/simple_text_scraper.py): input extraction · Extracts usable text from URLs and documents · `cm-backend/scrape/simple_text_scraper.py`
- [CLI build](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/build_cm_from_txt.py): text-to-map utility · Command-line path for concept map generation · `cm-backend/build_cm_from_txt.py`
- [Prompts](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/prompts/concept_extraction.py): prompt templates · Summarization and concept extraction prompts · `cm-backend/prompts/concept_extraction.py`
- [LLM schema](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/llm/models.py): structured models · Concept, relation, and map data structures · `cm-backend/llm/models.py`
- [Graph builder](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/visualize/graphviz_builder.py): visualization builder · Converts structured maps into Graphviz output · `cm-backend/visualize/graphviz_builder.py`
- [Evaluator](https://github.com/lennartkoepper/concept-mapper/blob/main/cm-backend/evaluate/graph_evaluator.py): graph metrics · Scores and analyzes generated concept graphs · `cm-backend/evaluate/graph_evaluator.py`

### External systems

LLM and rendering dependencies outside the repo

- **LLM APIs**: OpenAI/Mistral · External model providers for extraction and summarization
- **Graphviz**: rendering dependency · External graph rendering engine and formats

## Connections

- App shell → Routes: uses · Shell mounts routed screens
- App shell → API client: calls · UI delegates backend communication to the API service
- Text input → Payload: fills · Text input contributes to generation payload
- File upload → Payload: fills · Uploaded content contributes to generation payload
- URL input → Payload: fills · URL input contributes to generation payload
- Options UI → Options model: edits · Configuration screen controls generation settings
- API client → API entry: requests · Browser submits generation requests to backend API
- API entry → Scraper: ingests · Backend normalizes text from URLs or files
- API entry → Prompts: prompts · Backend assembles summarization and extraction prompts
- API entry → LLM schema: structures · Backend converts model output into graph-ready schema
- API entry → Graph builder: renders · Backend turns structured concept maps into graph output
- API entry → Evaluator: evaluates · Backend can score the resulting graph
- CLI build → Scraper: reuses · CLI path shares text ingestion logic
- CLI build → Prompts: reuses · CLI path shares prompt pipeline
- Prompts → LLM APIs: calls · Prompt pipeline uses external model providers
- LLM schema → LLM APIs: validated by · Structured schemas constrain LLM output
- Graph builder → Graphviz: targets · Graph builder emits Graphviz-compatible artifacts
- Graph builder → Evaluator: shares model · Evaluation consumes the same graph structure