How stevenmcsorley/private-legal-dms works
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