# rajapremsai/legaleaseai architecture

> Architecture diagram of the GitHub repository rajapremsai/legaleaseai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rajapremsai/legaleaseai
- Repository: https://github.com/rajapremsai/legaleaseai

## Overview

##### Project Type and Purpose
- This is a full-stack, AI-driven web application (“Legal Document AI Assistant”) built as a monorepo (Turborepo) with separate frontend and backend apps plus shared utilities.
- Its goal is to accept legal document uploads, process them through Google Cloud’s Document AI and Vertex AI for analysis, simplification, Q&A, risk assessment, etc., and present results via a responsive Next.js UI.

##### Top-Level Architectural Components
- Frontend (apps/frontend): Next.js/React-TypeScript PWA, served via Cloud Run (or CDN), handles user interactions, file upload UI, real-time Q&A chat, dashboards, and offline support.
- Backend API (apps/backend): Node.js/Express-TypeScript microservice exposing REST endpoints, implements authentication, document ingestion, AI orchestration, versioning, privacy, template library, risk assessment, analytics, and scheduler.
- Shared (packages/shared): Common TypeScript types, schemas, migration logic.
- Data Stores:
- Cloud Firestore (NoSQL) – for user sessions, workspace/document metadata, templates, audit logs.
- Cloud SQL (PostgreSQL) – for relational data: version control, complex queries, historical snapshots.
- Cloud Storage bucket – for binary document storage (PDF/DOCX/TXT).
- AI/ML Services (GCP):
- Document AI – OCR and structure extraction.
- Vertex AI (PaLM 2) – generative summarization, Q&A, risk assessment.
- Infrastructure:
- Cloud Run (frontend & backend).
- Cloud Build / GitHub Actions for CI/CD.
- Docker Compose for local dev.
- Deployment manifests for Cloud Run, autoscaling, environment parameterization.
- External Integrations: OAuth (Google IAM), Monitoring & Logging (Cloud Monitoring, Stackdriver).

##### Relationships & Data Flows
1. User (Browser/PWA) → Frontend Next.js
2. Frontend → REST API (Express) via HTTPS
3. API → Auth Service → Identity (Firebase Auth or custom)
4. API → Storage Service → Uploads file to Cloud Storage
5. API → Document AI (GCP) → structured output
6. API → Vertex AI for summarization/Q&A/risk assessment
7. API → Firestore & Cloud SQL (via repositories) to persist metadata, versions, audit logs
8. API → Returns processed data back to Frontend
9. Frontend → Renders dashboards, Q&A interface
10. Scheduler Service within API triggers periodic cleanups, auto-delete, template seeds, analytics jobs

##### Architectural Patterns & Principles
- Monolithic microservice for backend, subdivided by services (aiAnalysis, documentVersioning, auth, etc.).
- Repository pattern for data access.
- Middleware chain for auth, rate limiting, validation, performance, security.
- Shared code via npm workspace to enforce DRY (schemas, migrations, utils).
- CI/CD pipelines for lint, tests (unit, integration, e2e, performance, security), build, deploy.
- Infrastructure as Code: Cloud Run YAML, cloudbuild.yaml, docker-compose.yml.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client"
        direction TB
        Browser["Browser / PWA"]:::frontend
    end

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        NextFrontend["Next.js Frontend"]:::frontend
    end

    %% Shared Package
    Shared["Shared Utilities & Types"]:::shared

    %% Backend Layer
    subgraph "Backend API"
        direction TB
        ExpressAPI["Express API (index.ts)"]:::backend
        subgraph "Services"
            direction TB
            AuthService["Auth Service"]:::backend
            AuthMiddleware["Auth Middleware"]:::backend
            UploadService["Upload Service"]:::backend
            StorageService["Storage Service"]:::backend
            DocumentAIService["Document AI Orchestration"]:::ai
            AIAnalysis["AI Analysis"]:::ai
            QuestionAnswer["Question Answering"]:::ai
            RiskAssessment["Risk Assessment"]:::ai
            AIOptimization["AI Optimization Utility"]:::ai
            DocumentVersionService["Document Versioning Service"]:::backend
            TemplateService["Template Library Service"]:::backend
            SchedulerService["Scheduler Service"]:::backend
            AnalyticsService["Analytics Service"]:::backend
            AuditLogger["Audit Logger"]:::backend
            PrivacyService["Privacy & Compliance Service"]:::backend
            MonitoringService["Monitoring Service"]:::backend
            BulkProcessing["Bulk Processing Service"]:::backend
            DocumentComparison["Document Comparison Service"]:::backend
            WorkspaceService["Workspace Management Service"]:::backend
        end
        subgraph "Database & Repositories"
            direction TB
            DBConnection["DB Connection"]:::backend
            BaseRepo["Base Repository"]:::backend
            DocumentVersionRepo["Document Version Repo"]:::backend
            TemplateRepo["Template Repository"]:::backend
            BulkProcessingRepo["Bulk Processing Repo"]:::backend
            WorkspaceRepo["Workspace Repository"]:::backend
        end
    end

    %% AI/ML Services
    subgraph "GCP AI/ML Services"
        direction TB
        DocAI["Document AI"]:::ai
        VertexAI["Vertex AI"]:::ai
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        Firestore["Cloud Firestore"]:::data
        CloudSQL["Cloud SQL (Postgres)"]:::data
        StorageBucket["Cloud Storage Bucket"]:::data
    end

    %% Infrastructure
    subgraph "Infrastructure"
        direction TB
        CloudRunFE["Cloud Run (Frontend)"]:::infra
        CloudRunBE["Cloud Run (Backend)"]:::infra
        CloudBuild["Cloud Build"]:::infra
        GitHubActions["GitHub Actions"]:::infra
        DockerCompose["Docker Compose (Local Dev)"]:::infra
        CloudRunManifests["Cloud Run Manifests"]:::infra
    end

    %% Flows
    Browser -->|"HTTP/S"| NextFrontend
    NextFrontend -->|"REST API"| ExpressAPI
    NextFrontend --> Shared
    ExpressAPI -->|uses| Shared
    ExpressAPI -->|authenticate| AuthService
    ExpressAPI -->|middleware| AuthMiddleware
    ExpressAPI -->|upload| UploadService
    UploadService -->|store| StorageService
    ExpressAPI -->|invoke| DocumentAIService
    DocumentAIService -->|extract| DocAI
    ExpressAPI -->|invoke| AIAnalysis
    AIAnalysis -->|calls| VertexAI
    ExpressAPI -->|invoke| QuestionAnswer
    QuestionAnswer -->|calls| VertexAI
    ExpressAPI -->|invoke| RiskAssessment
    RiskAssessment -->|calls| VertexAI
    ExpressAPI -->|version| DocumentVersionService
    DocumentVersionService --> DocumentVersionRepo
    ExpressAPI -->|templates| TemplateService
    TemplateService --> TemplateRepo
    ExpressAPI -->|schedule| SchedulerService
    SchedulerService -->|cleanup| DocumentVersionRepo
    SchedulerService -->|analytics| AnalyticsService
    AnalyticsService --> AuditLogger
    ExpressAPI -->|privacy| PrivacyService
    ExpressAPI -->|monitor| MonitoringService
    ExpressAPI -->|bulk| BulkProcessing
    BulkProcessing --> BulkProcessingRepo
    ExpressAPI -->|compare| DocumentComparison
    ExpressAPI -->|workspace| WorkspaceService
    WorkspaceService --> WorkspaceRepo
    ExpressAPI -->|db conn| DBConnection
    DBConnection --> BaseRepo
    BaseRepo --> DocumentVersionRepo
    BaseRepo --> TemplateRepo
    BaseRepo --> BulkProcessingRepo
    BaseRepo --> WorkspaceRepo

    DocumentVersionRepo --> CloudSQL
    TemplateRepo --> CloudSQL
    BulkProcessingRepo --> CloudSQL
    WorkspaceRepo --> CloudSQL
    ExpressAPI -->|store metadata| Firestore
    AuthService -->|user sessions| Firestore
    AuditLogger -->|logs| Firestore
    UploadService -->|firestore rules| Firestore

    ExpressAPI -->|"response"| NextFrontend

    %% Infra Connections
    NextFrontend --> CloudRunFE
    ExpressAPI --> CloudRunBE
    CloudBuild --> CloudRunFE
    CloudBuild --> CloudRunBE
    GitHubActions --> CloudBuild
    DockerCompose --> NextFrontend
    DockerCompose --> ExpressAPI
    CloudRunManifests --> CloudRunFE
    CloudRunManifests --> CloudRunBE

    %% Click Events
    click NextFrontend "https://github.com/rajapremsai/legaleaseai/tree/main/apps/frontend/"
    click ExpressAPI "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/index.ts"
    click Shared "https://github.com/rajapremsai/legaleaseai/tree/main/packages/shared/src/"
    click AuthService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/auth.ts"
    click AuthMiddleware "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/middleware/auth.ts"
    click UploadService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/upload.ts"
    click StorageService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/storage.ts"
    click DocumentAIService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/documentAI.ts"
    click AIAnalysis "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/aiAnalysis.ts"
    click QuestionAnswer "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/questionAnswering.ts"
    click RiskAssessment "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/riskAssessment.ts"
    click AIOptimization "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/aiOptimization.ts"
    click DocumentVersionService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/documentVersioning.ts"
    click DocumentVersionRepo "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/database/repositories/documentVersionRepository.ts"
    click TemplateService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/templateService.ts"
    click TemplateRepo "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/database/repositories/templateRepository.ts"
    click SchedulerService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/scheduler.ts"
    click AnalyticsService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/analyticsService.ts"
    click AuditLogger "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/auditLogger.ts"
    click PrivacyService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/privacy.ts"
    click MonitoringService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/monitoring.ts"
    click BulkProcessing "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/bulkProcessingService.ts"
    click BulkProcessingRepo "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/database/repositories/bulkProcessingRepository.ts"
    click WorkspaceService "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/services/workspaceService.ts"
    click WorkspaceRepo "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/database/repositories/workspaceRepository.ts"
    click DBConnection "https://github.com/rajapremsai/legaleaseai/blob/main/apps/backend/src/database/connection.ts"
    click DockerCompose "https://github.com/rajapremsai/legaleaseai/blob/main/docker-compose.yml"
    click GitHubActions "https://github.com/rajapremsai/legaleaseai/blob/main/.github/workflows/ci.yml"
    click CloudBuild "https://github.com/rajapremsai/legaleaseai/blob/main/cloudbuild.yaml"
    click CloudRunManifests "https://github.com/rajapremsai/legaleaseai/tree/main/deployment/cloud-run/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef ai fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef shared fill:#EFE68C,stroke:#333,stroke-width:1px
```
