# crivano/apoia architecture

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

- Interactive diagram: https://gitdiagram.com/crivano/apoia
- Repository: https://github.com/crivano/apoia

## Overview

##### Project type and purpose
- This is a full-stack Next.js 13 application using the app/ directory for both client and server components.
- It provides a React-based UI (app/*.tsx, components/) and also implements API routes (app/api/…).
- It integrates AI services (lib/ai), PDF generation (lib/pdf), legal data interop (lib/interop), and a MySQL/Postgres database (lib/db + migrations).
- It uses NextAuth/Keycloak for authentication (app/auth/*, app/api/auth), Swagger/OpenAPI for documentation, and is deployed with Docker, GitLab CI/CD, and Kubernetes.

##### File structure
- Top-level “app/” folder: contains Next.js pages & API routes.
– app/page.tsx, app/layout.tsx: root layout
– app/abusive-litigation, app/arena, app/community, app/process, etc: domain-specific pages
– app/api/*: server-side API routes (REST endpoints under various versions)
- components/: shared React UI components
- lib/: core libraries for AI, database access, interop, PDF templating, utilities
- migrations/, seeds/: database schema and seed files for MySQL and Postgres
- Dockerfile, docker-compose.yaml, .gitlab-ci.yml, kubernetes/: containerization & deployment
- next-swagger-doc.json, public/swagger.json: OpenAPI specs

##### (empty) README for missing architecture notes
- The presence of kubernetes/overlays and Docker means you must represent container orchestration and CI/CD flow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entities
    Browser["Browser"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer"
        A["Next.js Frontend (app/)"]:::frontend
        B["Shared React Components (components/)"]:::frontend
        C["Global Layout & Styles (app/layout.tsx)"]:::frontend
    end

    %% Server/API Layer
    subgraph "Server/API Layer"
        D["API Routes (app/api/)"]:::api
        subgraph Actuator
            D1h["health route"]:::api
            D1i["info route"]:::api
        end
        subgraph Authentication Endpoints
            D2u["NextAuth route"]:::api
            D2o["NextAuth options"]:::api
        end
        subgraph Environment Endpoints
            D3a["Env route"]:::api
            D3b["Env test route"]:::api
        end
        subgraph PDF Endpoints
            D4["PDF route"]:::api
        end
        subgraph Versioned API v1
            D5["v1 routes"]:::api
        end
    end

    %% Auth UI
    subgraph "Authentication UI"
        E1["Keycloak UI"]:::api
        E2["Signin UI"]:::api
    end

    %% Core Libraries
    subgraph "Core Libraries"
        F1["AI Services (lib/ai/)"]:::domain
        F2["PDF Generation (lib/pdf/)"]:::domain
        F3["DB Abstraction (lib/db/)"]:::domain
        F4["Legal Data Interop (lib/interop/)"]:::domain
        F5["Service Discovery (lib/eureka.ts)"]:::domain
        F6["Domain Logic (lib/proc/)"]:::domain
        F7["Utilities & Shared Code (lib/utils/)"]:::domain
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        G["Database (MySQL/Postgres)"]:::db
    end

    %% API Documentation
    subgraph "API Documentation"
        H["Swagger UI & OpenAPI"]:::external
    end

    %% External Services
    subgraph "External Services"
        I1["AI Provider (OpenAI)"]:::external
        I2["Keycloak/OIDC"]:::external
    end

    %% CI/CD & Infrastructure
    subgraph "CI/CD & Infrastructure"
        J1["GitLab CI (.gitlab-ci.yml)"]:::infra
        J2["Docker & Compose"]:::infra
        J3["Kubernetes & Overlays"]:::infra
    end

    %% Connections
    Browser -->|"HTTP"| A
    A -->|"fetch()"| D
    D -->|"calls"| F1
    D -->|"calls"| F2
    D -->|"calls"| F3
    D -->|"calls"| F4
    D -->|"calls"| F6
    D -->|"calls"| F7
    F3 -->|"SQL queries"| G
    F1 -->|"HTTP requests"| I1
    D2u -->|"OAuth/OIDC"| I2
    D -->|"serves docs"| H
    J1 -->|"triggers"| J2
    J2 -->|"builds images"| J3
    J3 -->|"deploys pods"| A
    J3 -->|"deploys pods"| D

    %% Click Events
    click A "https://github.com/crivano/apoia/tree/main/app/"
    click B "https://github.com/crivano/apoia/tree/main/components/"
    click C "https://github.com/crivano/apoia/blob/main/app/layout.tsx"
    click D "https://github.com/crivano/apoia/tree/main/app/api/"
    click D1h "https://github.com/crivano/apoia/blob/main/app/api/actuator/health/route.ts"
    click D1i "https://github.com/crivano/apoia/blob/main/app/api/actuator/info/route.ts"
    click D2u "https://github.com/crivano/apoia/blob/main/app/api/auth/[...nextauth]/route.ts"
    click D2o "https://github.com/crivano/apoia/blob/main/app/api/auth/[...nextauth]/options.ts"
    click D3a "https://github.com/crivano/apoia/blob/main/app/api/env/route.ts"
    click D3b "https://github.com/crivano/apoia/blob/main/app/api/env/test/route.ts"
    click D4 "https://github.com/crivano/apoia/blob/main/app/api/pdf/[id]/route.ts"
    click D5 "https://github.com/crivano/apoia/tree/main/app/api/v1/"
    click E1 "https://github.com/crivano/apoia/blob/main/app/auth/keycloak/page.jsx"
    click E2 "https://github.com/crivano/apoia/blob/main/app/auth/signin/page.jsx"
    click F1 "https://github.com/crivano/apoia/tree/main/lib/ai/"
    click F2 "https://github.com/crivano/apoia/blob/main/lib/pdf/pdf.ts"
    click F3 "https://github.com/crivano/apoia/blob/main/lib/db/knex.ts"
    click F4 "https://github.com/crivano/apoia/blob/main/lib/interop/interop.ts"
    click F5 "https://github.com/crivano/apoia/blob/main/lib/eureka.ts"
    click F6 "https://github.com/crivano/apoia/tree/main/lib/proc/"
    click F7 "https://github.com/crivano/apoia/tree/main/lib/utils/"
    click H "https://github.com/crivano/apoia/blob/main/public/swagger.json"
    click J1 "https://github.com/crivano/apoia/blob/main/.gitlab-ci.yml"
    click J2 "https://github.com/crivano/apoia/tree/main/Dockerfile"
    click J3 "https://github.com/crivano/apoia/tree/main/kubernetes/"

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef api fill:#DFF8E0,stroke:#28A745,color:#28A745
    classDef domain fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00
    classDef db fill:#F5E1DA,stroke:#A52A2A,color:#A52A2A
    classDef external fill:#E2E3E5,stroke:#6C757D,color:#6C757D
    classDef infra fill:#E8D5F8,stroke:#6F42C1,color:#6F42C1
```
