# zas512/verdict architecture

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

## Overview

Verdict is a law-firm management platform: firm users work through the web dashboard, authenticate and manage matters and related business operations through the NestJS API, with PostgreSQL-backed domain services. For legal-document assistance, the API proxies chat, query and upload requests to a separate Python RAG service. That service parses and chunks documents, embeds and indexes them, then retrieves matter-scoped context for guarded LLM responses. README documents HR, expenses, case-document versioning and other capabilities not represented by sampled controller excerpts; those branches are shown at their supported module paths. RAG wiring is evidenced by the sampled routes and ingestion pipeline.

Main entry points: [`apps/web/src/app/api/[...path]/route.ts`](https://github.com/zas512/verdict/blob/main/apps/web/src/app/api/%5B...path%5D/route.ts) (Web API routes), [`apps/ai/src/api/routes.py`](https://github.com/zas512/verdict/blob/main/apps/ai/src/api/routes.py) (RAG API), [`apps/api/src/modules/auth/auth.service.ts`](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/auth/auth.service.ts) (Identity and access), [`apps/api/src/modules/tasks/tasks.controller.ts`](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/tasks/tasks.controller.ts) (Tasks and files)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_dashboard["Dashboard workflows"]
  node_webproxy["Web API routes<br/>[route.ts]"]
end

subgraph group_api["Business API"]
  node_auth["Identity and access<br/>[auth.service.ts]"]
  node_firms["Firm administration"]
  node_matters["Matter lifecycle"]
  node_clients["Client management"]
  node_documents["Case documents"]
  node_tasks["Tasks and files"]
  node_people["Associates and users"]
  node_attendance["Attendance and leave"]
  node_expenses["Expense management"]
  node_hearings["Hearings"]
  node_ai_gateway["AI gateway<br/>[ai.controller.ts]"]
end

subgraph group_rag["Legal AI"]
  node_ai_routes["RAG API<br/>[routes.py]"]
  node_ingestion["Document ingestion<br/>[pipeline.py]"]
  node_retrieval["Matter retrieval<br/>[retriever.py]"]
  node_generation["Guarded generation<br/>[llm.py]"]
end

subgraph group_infra["Persistence and services"]
  node_vectors[("Vector store<br/>[vector_store.py]")]
  node_postgres[("PostgreSQL")]
end

node_staff(("Firm user"))
node_ollama["Ollama models"]
node_cloudinary["Cloudinary"]
node_mail["Email delivery<br/>[mail.service.ts]"]

node_staff -->|"uses"| node_dashboard
node_dashboard -->|"requests"| node_webproxy
node_webproxy -->|"authenticates"| node_auth
node_webproxy -->|"manages matters"| node_matters
node_webproxy -->|"manages clients"| node_clients
node_webproxy -->|"manages documents"| node_documents
node_webproxy -->|"manages tasks"| node_tasks
node_webproxy -->|"manages people"| node_people
node_webproxy -->|"tracks attendance"| node_attendance
node_webproxy -->|"manages expenses"| node_expenses
node_webproxy -->|"manages hearings"| node_hearings
node_webproxy -->|"administers firms"| node_firms
node_auth -->|"reads and writes"| node_postgres
node_firms -->|"reads and writes"| node_postgres
node_matters -->|"reads and writes"| node_postgres
node_clients -->|"reads and writes"| node_postgres
node_documents -->|"reads and writes"| node_postgres
node_tasks -->|"reads and writes"| node_postgres
node_people -->|"reads and writes"| node_postgres
node_attendance -->|"reads and writes"| node_postgres
node_expenses -->|"reads and writes"| node_postgres
node_hearings -->|"reads and writes"| node_postgres
node_auth -->|"sends invitations"| node_mail
node_tasks -.->|"requests signatures"| node_cloudinary
node_webproxy -->|"requests AI"| node_ai_gateway
node_ai_gateway -->|"proxies requests"| node_ai_routes
node_ai_routes -->|"indexes uploads"| node_ingestion
node_ingestion -->|"writes embeddings"| node_vectors
node_ai_routes -->|"searches matter context"| node_retrieval
node_retrieval -->|"queries chunks"| node_vectors
node_ai_routes -->|"generates responses"| node_generation
node_generation -.->|"calls models"| node_ollama

click node_dashboard "https://github.com/zas512/verdict/tree/main/apps/web/src/app/(dashboard)"
click node_webproxy "https://github.com/zas512/verdict/blob/main/apps/web/src/app/api/%5B...path%5D/route.ts"
click node_auth "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_firms "https://github.com/zas512/verdict/tree/main/apps/api/src/modules/firms"
click node_matters "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/matters/matters.controller.ts"
click node_clients "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/clients/clients.controller.ts"
click node_documents "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/case-documents/case-documents.controller.ts"
click node_tasks "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/tasks/tasks.controller.ts"
click node_people "https://github.com/zas512/verdict/tree/main/apps/api/src/modules/hr/associates"
click node_attendance "https://github.com/zas512/verdict/tree/main/apps/api/src/modules/hr/attendance"
click node_expenses "https://github.com/zas512/verdict/tree/main/apps/api/src/modules/expenses"
click node_hearings "https://github.com/zas512/verdict/tree/main/apps/api/src/modules/matters/hearings"
click node_ai_gateway "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/ai/ai.controller.ts"
click node_ai_routes "https://github.com/zas512/verdict/blob/main/apps/ai/src/api/routes.py"
click node_ingestion "https://github.com/zas512/verdict/blob/main/apps/ai/src/ingestion/pipeline.py"
click node_retrieval "https://github.com/zas512/verdict/blob/main/apps/ai/src/retrieval/retriever.py"
click node_generation "https://github.com/zas512/verdict/blob/main/apps/ai/src/generation/llm.py"
click node_vectors "https://github.com/zas512/verdict/blob/main/apps/ai/src/retrieval/vector_store.py"
click node_mail "https://github.com/zas512/verdict/blob/main/apps/api/src/modules/mail/mail.service.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_dashboard,node_webproxy,node_staff toneBlue
class node_auth,node_firms,node_matters,node_clients,node_documents,node_tasks,node_people,node_attendance,node_expenses,node_hearings,node_ai_gateway toneAmber
class node_ai_routes,node_ingestion,node_retrieval,node_generation toneMint
class node_vectors,node_postgres toneRose
class node_ollama,node_cloudinary toneIndigo
class node_mail toneTeal
```

## Components

### Web experience

- [Dashboard workflows](https://github.com/zas512/verdict/tree/main/apps/web/src/app/(dashboard)): `apps/web/src/app/(dashboard)`
- [Web API routes](https://github.com/zas512/verdict/blob/main/apps/web/src/app/api/%5B...path%5D/route.ts): `apps/web/src/app/api/[...path]/route.ts`

### Business API

- [Identity and access](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [Firm administration](https://github.com/zas512/verdict/tree/main/apps/api/src/modules/firms): `apps/api/src/modules/firms`
- [Matter lifecycle](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/matters/matters.controller.ts): `apps/api/src/modules/matters/matters.controller.ts`
- [Client management](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/clients/clients.controller.ts): `apps/api/src/modules/clients/clients.controller.ts`
- [Case documents](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/case-documents/case-documents.controller.ts): `apps/api/src/modules/case-documents/case-documents.controller.ts`
- [Tasks and files](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/tasks/tasks.controller.ts): `apps/api/src/modules/tasks/tasks.controller.ts`
- [Associates and users](https://github.com/zas512/verdict/tree/main/apps/api/src/modules/hr/associates): `apps/api/src/modules/hr/associates`
- [Attendance and leave](https://github.com/zas512/verdict/tree/main/apps/api/src/modules/hr/attendance): `apps/api/src/modules/hr/attendance`
- [Expense management](https://github.com/zas512/verdict/tree/main/apps/api/src/modules/expenses): `apps/api/src/modules/expenses`
- [Hearings](https://github.com/zas512/verdict/tree/main/apps/api/src/modules/matters/hearings): `apps/api/src/modules/matters/hearings`
- [AI gateway](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/ai/ai.controller.ts): `apps/api/src/modules/ai/ai.controller.ts`

### Legal AI

- [RAG API](https://github.com/zas512/verdict/blob/main/apps/ai/src/api/routes.py): `apps/ai/src/api/routes.py`
- [Document ingestion](https://github.com/zas512/verdict/blob/main/apps/ai/src/ingestion/pipeline.py): `apps/ai/src/ingestion/pipeline.py`
- [Matter retrieval](https://github.com/zas512/verdict/blob/main/apps/ai/src/retrieval/retriever.py): `apps/ai/src/retrieval/retriever.py`
- [Guarded generation](https://github.com/zas512/verdict/blob/main/apps/ai/src/generation/llm.py): `apps/ai/src/generation/llm.py`

### Persistence and services

- [Vector store](https://github.com/zas512/verdict/blob/main/apps/ai/src/retrieval/vector_store.py): `apps/ai/src/retrieval/vector_store.py`
- **PostgreSQL**

### Other components

- **Firm user**
- **Ollama models**
- **Cloudinary**
- [Email delivery](https://github.com/zas512/verdict/blob/main/apps/api/src/modules/mail/mail.service.ts): `apps/api/src/modules/mail/mail.service.ts`

## Connections

- Firm user → Dashboard workflows: uses
- Dashboard workflows → Web API routes: requests
- Web API routes → Identity and access: authenticates
- Web API routes → Matter lifecycle: manages matters
- Web API routes → Client management: manages clients
- Web API routes → Case documents: manages documents
- Web API routes → Tasks and files: manages tasks
- Web API routes → Associates and users: manages people
- Web API routes → Attendance and leave: tracks attendance
- Web API routes → Expense management: manages expenses
- Web API routes → Hearings: manages hearings
- Web API routes → Firm administration: administers firms
- Identity and access → PostgreSQL: reads and writes
- Firm administration → PostgreSQL: reads and writes
- Matter lifecycle → PostgreSQL: reads and writes
- Client management → PostgreSQL: reads and writes
- Case documents → PostgreSQL: reads and writes
- Tasks and files → PostgreSQL: reads and writes
- Associates and users → PostgreSQL: reads and writes
- Attendance and leave → PostgreSQL: reads and writes
- Expense management → PostgreSQL: reads and writes
- Hearings → PostgreSQL: reads and writes
- Identity and access → Email delivery: sends invitations
- Tasks and files → Cloudinary: requests signatures
- Web API routes → AI gateway: requests AI
- AI gateway → RAG API: proxies requests
- RAG API → Document ingestion: indexes uploads
- Document ingestion → Vector store: writes embeddings
- RAG API → Matter retrieval: searches matter context
- Matter retrieval → Vector store: queries chunks
- RAG API → Guarded generation: generates responses
- Guarded generation → Ollama models: calls models