# stevenmcsorley/private-legal-dms architecture

> Architecture diagram of the GitHub repository stevenmcsorley/private-legal-dms, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stevenmcsorley/private-legal-dms
- Repository: https://github.com/stevenmcsorley/private-legal-dms

## Overview

##### Project Type and Purpose
- This is a full-stack, self-hosted enterprise application: a Private Legal Document Management System.
- It combines a React-based SPA frontend, a NestJS backend API with integrated background processing, and a rich document-processing pipeline.
- Key goals: zero-trust security, WORM-compliant storage, clearance-based access control, audit trails, and enterprise observability.

##### High-Level Architectural Components
a. Frontend
- React 18 + TypeScript SPA (services/frontend/)
- Vite build, served via Nginx or static hosting behind Traefik
- UI modules: authentication, admin, client portal, document viewer, search

b. API Gateway
- Traefik for TLS termination, routing, mTLS between services (defined in docker-compose.yml / infra)

c. Backend API
- NestJS monolith (services/app/) exposing REST/BFF endpoints
- Feature modules: auth, clients, matters, documents, shares, legal-holds, admin, audit, metrics, health
- Uses TypeORM → PostgreSQL; integrates with Keycloak (OIDC) and OPA for authorization

d. Document Processing Pipeline
- Redis + Bull queue (services/app/src/common/queues/)
- Workers for virus scanning (ClamAV), text extraction (Apache Tika), OCR (Tesseract), PDF conversion, watermarking
- Output indexed into OpenSearch; binary blobs stored in MinIO with Object Lock

e. Data Layer
- PostgreSQL (ACID primary database)
- OpenSearch (full-text search with OCR text indexing)
- MinIO (S3-compatible WORM storage)
- Redis (message queue for background jobs)

f. Identity & Authorization
- Keycloak (infra/keycloak/) for authentication, MFA, user/firm/role management
- Open Policy Agent (infra/opa/) for centralized Rego-based authorization

g. Observability & Security
- Prometheus (infra/prometheus/) for metrics collection
- Grafana (infra/grafana/) dashboards
- Loki (infra/loki/) for log aggregation
- Vault for secrets management (implied)
- Security CI pipelines (OWASP ZAP, Trivy, OPA tests) under docs/Security CI

##### Relationships & Data Flows
- User’s browser → (HTTPS) → Traefik → NestJS API
- Authentication handshake with Keycloak
- API → OPA for every protected operation
- NestJS API → PostgreSQL (TypeORM ORM calls)
- NestJS API → Redis enqueue jobs → Workers → Tika/OCR/ClamAV
- Workers → MinIO (document blob storage)
- Workers → OpenSearch (indexing)
- NestJS API → OpenSearch (search queries)
- NestJS API → Prometheus (metrics endpoint)
- Prometheus → Grafana (dashboards), Loki ingestion via API

##### Architectural Patterns & Principles
- Microservices-style logical separation (API modules, background workers)
- CQRS flavour: read path via OpenSearch, write path via PostgreSQL + events
- Zero-trust: mTLS, OPA policies, per-request authorization
- Immutable storage: MinIO Object Lock for WORM compliance
- Event-driven processing: Redis/Bull for asynchronous pipelines

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (UI Layer)"
        direction TB
        UI["UI: React SPA<br/>React 18 + TypeScript"]:::frontend
        AuthUI["Auth Module"]:::frontend
        AdminUI["Admin Module"]:::frontend
        ClientUI["Client Portal Module"]:::frontend
        DocsUI["Document Viewer & Listing"]:::frontend
        SearchUI["Search Page"]:::frontend
    end

    %% API Gateway
    TG["API Gateway: Traefik<br/>TLS Termination, mTLS"]:::gateway

    %% Backend & Workers
    subgraph "Backend Services"
        direction TB
        API["API: NestJS Monolith<br/>TypeORM"]:::backend
        subgraph "Feature Modules"
            direction TB
            AuthAPI["Auth Module"]:::backend
            ClientsAPI["Clients Module"]:::backend
            MattersAPI["Matters Module"]:::backend
            DocsAPI["Documents Module"]:::backend
            SharesAPI["Shares Module"]:::backend
            HoldsAPI["Legal Holds Module"]:::backend
            AdminAPI["Admin Module"]:::backend
            AuditAPI["Audit Module"]:::backend
            HealthAPI["Health & Metrics Module"]:::backend
        end
        subgraph "Processing Pipeline"
            direction TB
            Queue["Redis + Bull Queue"]:::backend
            Worker["Workers<br/>Tika, OCR, ClamAV, Watermark"]:::backend
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        Postgres[(PostgreSQL)]:::data
        Redis[(Redis)]:::data
        OpenSearch[(OpenSearch)]:::data
        MinIO[(MinIO WORM Storage)]:::data
    end

    %% Identity & Authorization
    subgraph "Identity & Authorization"
        direction TB
        Keycloak["Auth: Keycloak"]:::infra
        OPA["AuthZ: OPA"]:::infra
    end

    %% Observability
    subgraph "Observability"
        direction TB
        Prom["Prometheus"]:::obs
        Graf["Grafana"]:::obs
        Loki["Loki"]:::obs
    end

    %% Flows
    UI -->|"HTTPS"| TG
    TG -->|"HTTPS"| API
    API -->|"OIDC"| Keycloak
    API -->|"gRPC/HTTP"| OPA
    API -->|"SQL"| Postgres
    API -->|"AMQP/Redis"| Queue
    API -->|"Search Queries"| OpenSearch
    API -->|"Metrics Endpoint"| Prom
    Queue -->|"Jobs"| Worker
    Worker -->|"Store Blobs"| MinIO
    Worker -->|"Index Text"| OpenSearch
    Prom -->|"Scrape Metrics"| Graf
    Prom -->|"Send Logs"| Loki

    %% Click events - Frontend
    click UI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/frontend/"
    click AuthUI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/frontend/src/components/auth/"
    click AdminUI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/frontend/src/components/admin/"
    click ClientUI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/frontend/src/components/client/"
    click DocsUI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/frontend/src/components/documents/"
    click SearchUI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/frontend/src/components/search/"

    %% Click events - API Gateway
    click TG "https://github.com/stevenmcsorley/private-legal-dms/blob/main/docker-compose.yml"

    %% Click events - Backend API
    click API "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/"
    click AuthAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/auth/"
    click ClientsAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/clients/"
    click MattersAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/matters/"
    click DocsAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/documents/"
    click SharesAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/shares/"
    click HoldsAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/legal-holds/"
    click AdminAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/admin/"
    click AuditAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/audit/"
    click HealthAPI "https://github.com/stevenmcsorley/private-legal-dms/tree/main/services/app/src/modules/health/"
    
    %% Click events - Processing Pipeline
    click Queue "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/common/queues/document-processing.queue.ts"
    click Worker "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/common/processors/document-processing.processor.ts"
    click DocsAPI "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/modules/documents/services/watermark.service.ts"
    click Worker "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/common/services/text-extraction.service.ts"
    click Worker "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/common/services/minio.service.ts"
    click Worker "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/common/services/opensearch.service.ts"

    %% Click events - Data Layer Config
    click Postgres "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/config/typeorm.config.ts"
    click Redis "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/config/redis.config.ts"
    click MinIO "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/config/minio.config.ts"
    click OpenSearch "https://github.com/stevenmcsorley/private-legal-dms/blob/main/services/app/src/common/services/opensearch.service.ts"

    %% Click events - Identity & Auth Infra
    click Keycloak "https://github.com/stevenmcsorley/private-legal-dms/blob/main/infra/keycloak/realm-export/dms-realm.json"
    click OPA "https://github.com/stevenmcsorley/private-legal-dms/blob/main/infra/opa/policy.rego"

    %% Click events - Observability Infra
    click Prom "https://github.com/stevenmcsorley/private-legal-dms/blob/main/infra/prometheus/prometheus.yml"
    click Graf "https://github.com/stevenmcsorley/private-legal-dms/blob/main/infra/grafana/provisioning/dashboards/dashboards.yml"
    click Loki "https://github.com/stevenmcsorley/private-legal-dms/blob/main/infra/loki/loki-config.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#007BFF,color:#000
    classDef gateway fill:#E5D0FF,stroke:#9C27B0,color:#000
    classDef backend fill:#D0F0D8,stroke:#388E3C,color:#000
    classDef data fill:#E0F7FA,stroke:#006064,color:#000
    classDef infra fill:#FFE0B2,stroke:#FB8C00,color:#000
    classDef obs fill:#FFF9C4,stroke:#FBC02D,color:#000
```
