# dbis-legal-llms/gripl-v2 architecture

> Architecture diagram of the GitHub repository dbis-legal-llms/gripl-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dbis-legal-llms/gripl-v2
- Repository: https://github.com/dbis-legal-llms/gripl-v2

## Overview

GRIPL supports BPMN process analysis, GDPR-grounded reasoning, dataset labeling, and evaluation. Users submit or model a process in the frontend; the backend extracts BPMN elements and coordinates an analyzer, optionally augmenting its reasoning through the sibling RAG service. Researchers can create and label evaluation datasets, then run evaluations and inspect reports. The RAG service retrieves context from a Neo4j-backed knowledge graph and also exposes PDF and RAG-evaluation APIs. The README establishes the product capabilities; several routes and integrations are unsampled, so those links are omitted unless documented or evidenced in the index.

Main entry points: [`gripl/gripl-frontend/src/app/page.tsx`](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/app/page.tsx) (GRIPL interface), [`gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt`](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt) (Analyzer factory), [`gripl/gripl-rag/app/api/routes.py`](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/api/routes.py) (RAG API), [`gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/adapter/rag/RagApiClient.kt`](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/adapter/rag/RagApiClient.kt) (RAG API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User workflows"]
  node_frontend["GRIPL interface<br/>[page.tsx]"]
  node_process_ui["Process analysis UI"]
  node_labeling_ui["Dataset labeling UI"]
  node_evaluation_ui["Evaluation UI"]
end

subgraph group_backend["GRIPL backend"]
  node_analysis["Analysis service<br/>[AnalysisService.kt]"]
  node_analyzer_factory["Analyzer factory<br/>[AnalyzerFactory.kt]"]
  node_bpmn["BPMN extraction<br/>[BpmnExtractor.kt]"]
  node_ai_analysis["LLM analysis"]
  node_rag_client["RAG API client<br/>[RagApiClient.kt]"]
  node_label_service["Label service<br/>[LabelService.kt]"]
  node_dataset_transfer["Dataset transfer"]
  node_process_store[("Process models")]
end

subgraph group_rag["RAG service"]
  node_rag_api["RAG API<br/>[routes.py]"]
  node_rag_engine["Retrieval engine<br/>[engine.py]"]
  node_graph_store[("Knowledge graph")]
  node_pdf_api["PDF lookup<br/>[pdf_routes.py]"]
end

subgraph group_evaluation["Evaluation"]
  node_rag_evaluator["RAG evaluator<br/>[ragas_evaluator.py]"]
  node_eval_runner["Evaluation runner"]
end

node_user(("User"))
node_postgres[("PostgreSQL")]
node_auth_service["Auth service"]

node_user -->|"uses"| node_frontend
node_frontend -->|"opens"| node_process_ui
node_frontend -->|"opens"| node_labeling_ui
node_frontend -->|"opens"| node_evaluation_ui
node_user -->|"authenticates via"| node_auth_service
node_analysis -->|"selects"| node_analyzer_factory
node_analyzer_factory -->|"configures"| node_rag_client
node_analyzer_factory -->|"selects"| node_ai_analysis
node_rag_client -->|"queries"| node_rag_api
node_rag_api -->|"retrieves with"| node_rag_engine
node_rag_engine -.->|"queries"| node_graph_store
node_dataset_transfer -->|"imports and exports"| node_postgres
node_label_service -.->|"persists labels"| node_postgres
node_eval_runner -->|"scores RAG"| node_rag_evaluator
node_rag_api -->|"also serves"| node_pdf_api

click node_frontend "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/app/page.tsx"
click node_process_ui "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/components/process-analysis/process-model-detail-view.tsx"
click node_labeling_ui "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/components/labeling/labeling-editor.tsx"
click node_evaluation_ui "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/components/evaluation/evaluation-page.tsx"
click node_analysis "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalysisService.kt"
click node_analyzer_factory "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt"
click node_bpmn "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/BpmnExtractor.kt"
click node_ai_analysis "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/ai/PromptBpmnAnalysisAiService.kt"
click node_rag_client "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/adapter/rag/RagApiClient.kt"
click node_label_service "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/LabelService.kt"
click node_dataset_transfer "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/dataset/DatasetTransferService.kt"
click node_process_store "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/repository/ProcessModelRepository.kt"
click node_rag_api "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/api/routes.py"
click node_rag_engine "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/rag/engine.py"
click node_pdf_api "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/api/pdf_routes.py"
click node_rag_evaluator "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/evaluation/ragas_evaluator.py"
click node_eval_runner "https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/evaluation/EvaluationRunner.kt"

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_frontend,node_process_ui,node_labeling_ui,node_evaluation_ui,node_user toneBlue
class node_analysis,node_analyzer_factory,node_bpmn,node_ai_analysis,node_rag_client,node_label_service,node_dataset_transfer,node_process_store,node_postgres toneAmber
class node_rag_api,node_rag_engine,node_graph_store,node_pdf_api toneMint
class node_rag_evaluator,node_eval_runner toneRose
class node_auth_service toneIndigo
```

## Components

### User workflows

- [GRIPL interface](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/app/page.tsx): `gripl/gripl-frontend/src/app/page.tsx`
- [Process analysis UI](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/components/process-analysis/process-model-detail-view.tsx): `gripl/gripl-frontend/src/components/process-analysis/process-model-detail-view.tsx`
- [Dataset labeling UI](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/components/labeling/labeling-editor.tsx): `gripl/gripl-frontend/src/components/labeling/labeling-editor.tsx`
- [Evaluation UI](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-frontend/src/components/evaluation/evaluation-page.tsx): `gripl/gripl-frontend/src/components/evaluation/evaluation-page.tsx`

### GRIPL backend

- [Analysis service](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalysisService.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalysisService.kt`
- [Analyzer factory](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt`
- [BPMN extraction](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/BpmnExtractor.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/BpmnExtractor.kt`
- [LLM analysis](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/ai/PromptBpmnAnalysisAiService.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/ai/PromptBpmnAnalysisAiService.kt`
- [RAG API client](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/adapter/rag/RagApiClient.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/adapter/rag/RagApiClient.kt`
- [Label service](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/LabelService.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/LabelService.kt`
- [Dataset transfer](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/dataset/DatasetTransferService.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/dataset/DatasetTransferService.kt`
- [Process models](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/repository/ProcessModelRepository.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/repository/ProcessModelRepository.kt`

### RAG service

- [RAG API](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/api/routes.py): `gripl/gripl-rag/app/api/routes.py`
- [Retrieval engine](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/rag/engine.py): `gripl/gripl-rag/app/rag/engine.py`
- **Knowledge graph**
- [PDF lookup](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/api/pdf_routes.py): `gripl/gripl-rag/app/api/pdf_routes.py`

### Evaluation

- [RAG evaluator](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-rag/app/evaluation/ragas_evaluator.py): `gripl/gripl-rag/app/evaluation/ragas_evaluator.py`
- [Evaluation runner](https://github.com/dbis-legal-llms/gripl-v2/blob/main/gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/evaluation/EvaluationRunner.kt): `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/evaluation/EvaluationRunner.kt`

### Other components

- **User**
- **PostgreSQL**
- **Auth service**

## Connections

- User → GRIPL interface: uses (evidence: `README.md`)
- GRIPL interface → Process analysis UI: opens (evidence: `README.md`)
- GRIPL interface → Dataset labeling UI: opens (evidence: `README.md`)
- GRIPL interface → Evaluation UI: opens (evidence: `README.md`)
- User → Auth service: authenticates via (evidence: `README.md`)
- Analysis service → Analyzer factory: selects (evidence: `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalysisService.kt`)
- Analyzer factory → RAG API client: configures (evidence: `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt`)
- Analyzer factory → LLM analysis: selects (evidence: `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/analyzer/AnalyzerFactory.kt`)
- RAG API client → RAG API: queries (evidence: `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/adapter/rag/RagApiClient.kt`)
- RAG API → Retrieval engine: retrieves with (evidence: `gripl/gripl-rag/app/api/routes.py`)
- Retrieval engine → Knowledge graph: queries
- Dataset transfer → PostgreSQL: imports and exports (evidence: `gripl/gripl-backend/src/main/kotlin/de/mertendieckmann/griplbackend/application/dataset/DatasetTransferService.kt`)
- Label service → PostgreSQL: persists labels
- Evaluation runner → RAG evaluator: scores RAG
- RAG API → PDF lookup: also serves (evidence: `gripl/gripl-rag/app/main.py`)
