How lennartkoepper/concept-mapper works
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: concept_mapper_api.py API entry · graphviz_builder.py Graph builder · concept_extraction.py Prompts · payload.ts Payload
Components 18
Angular UI
Browser client for input, options, and result display
- App shell · Routes and top-level UI composition
cm-frontend/src/app/app.component.ts - Routes · Navigation and screen wiring
cm-frontend/src/app/app.routes.ts - API client · Browser-to-backend request boundary
cm-frontend/src/app/_services/api.service.ts - Payload · Structured generation request/response contract
cm-frontend/src/app/_shared/payload.ts - Options model · Generation settings used by the UI
cm-frontend/src/app/_shared/options.ts - Text input · Direct text entry workflow
cm-frontend/src/app/text-uploader/text-uploader.component.ts - File upload · Document upload workflow
cm-frontend/src/app/file-upload/file-upload.component.ts - URL input · Web-source input workflow
cm-frontend/src/app/url-provider/url-provider.component.ts - Options UI · Model, size, and prompt options
cm-frontend/src/app/options/options.component.ts
Python backend
API, ingestion, generation, rendering, and evaluation
- API entry · Backend request orchestrator
cm-backend/concept_mapper_api.py - Scraper · Extracts usable text from URLs and documents
cm-backend/scrape/simple_text_scraper.py - CLI build · Command-line path for concept map generation
cm-backend/build_cm_from_txt.py - Prompts · Summarization and concept extraction prompts
cm-backend/prompts/concept_extraction.py - LLM schema · Concept, relation, and map data structures
cm-backend/llm/models.py - Graph builder · Converts structured maps into Graphviz output
cm-backend/visualize/graphviz_builder.py - Evaluator · Scores and analyzes generated concept graphs
cm-backend/evaluate/graph_evaluator.py
External systems
LLM and rendering dependencies outside the repo
- LLM APIs · External model providers for extraction and summarization
- Graphviz · External graph rendering engine and formats
Connections 18
- 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