# quartermasters/epaethicsapp architecture

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

- Interactive diagram: https://gitdiagram.com/quartermasters/epaethicsapp
- Repository: https://github.com/quartermasters/epaethicsapp

## Overview

##### Project Type & Purpose
- This is a full-stack, cross-platform federal ethics training system (“EthicsGo”) composed of:
– A React-based Admin Portal (Next.js)
– A React Native mobile app (Expo)
– A Node.js backend API (Express/Fastify)
- Mission: Deliver compliant, accessible, secure ethics training with AI-powered learning paths, real-time analytics, and multi-platform sync.

##### High-Level File-Structure Analysis
- Top-level directories:
– admin-portal → Next.js app (app folder, components, content-management, quiz-editor, auth pages, styling, Tailwind, TypeScript).
– mobile → Expo/React Native app (App.tsx, src/components, src/screens, AuthContext, services/api, assets, design system).
– backend → Node.js API (routes, middleware, config, utils, tests, Dockerfile, database init.sql).
– docs/Documentation → Compliance and project documentation.
- Root config: docker-compose.yml, .env.example, CI/CD workflows (.github), Dockerfiles in each service, shell scripts for local startup (start-*.sh), tests/integration.

##### README Insights
- Technology stacks: React Native 0.72/Next.js 14, Node 20+, Express/Fastify, GraphQL + REST, PostgreSQL 16, Redis, Docker Swarm/ECS, GitHub Actions, OAuth2/OIDC, JWT, WAF, Vault.
- Emphasizes FedRAMP, WCAG compliance, performance targets, CI/CD pipeline, monitoring, future roadmap.

a. Main Components
- Clients: Mobile App (Expo), Web Admin Portal (Next.js), Desktop PWA (planned).
- API Gateway: Single ingress for REST and GraphQL.
- Backend Services:
– Auth Service (OAuth2/OIDC, JWT issuance, refresh token flow).
– Core API (modules, progress, quiz engine) implemented in Express/Fastify.
– AI Engine (personalization, learning‐path generator).
– Analytics Hub (real-time progress analytics, time-series DB).
- Data Stores: PostgreSQL (primary relational store), Time Series DB (analytics), Redis (cache/session).
- Cross-cutting: Security Layer (WAF, rate limiting, zero-trust), Logging & Monitoring (Prometheus, Grafana, SIEM).
- CI/CD & Infrastructure: GitHub Actions → Docker images → AWS ECS Fargate/Kubernetes → Terraform, Auto-scaling, Multi-cloud.

b. Relationships & Data Flows
- Clients → API Gateway: authenticated calls over HTTPS.
- API Gateway → Auth Service: token validation, user info.
- API Gateway → Core API → DB.
- Core API → AI Engine & Analytics via internal RPC/HTTP.
- Analytics Hub writes metrics to Time Series DB.
- Background jobs / Redis used for rate-limit counters, session store.
- CI/CD updates containers → orchestrator → service mesh.
- Monitoring tools pull metrics from API, AI Engine, DB; alerts to SIEM.

c. Architectural Patterns & Principles
- Microservices-in-containers (Auth, Core API, AI, Analytics separated).
- API Gateway pattern (single entry point, routing, security enforcement).
- CQRS for analytics (separate write path vs. read path).
- Zero-trust network (service-to-service auth, Vault for secrets).
- Infrastructure as Code & GitOps for reproducible deployments.

d. Key Technologies to Call Out
- Frontend: Next.js (App Router), React Native + Expo SDK 49, TypeScript.
- Backend: Node.js, Express.js / Fastify, GraphQL & REST.
- Databases: PostgreSQL 16, Redis, Time Series (e.g., InfluxDB).
- DevOps: GitHub Actions, Docker, AWS ECS Fargate, Kubernetes, Terraform.
- Security: OAuth2/OIDC, JWT, WAF, Vault, Rate Limiting.
- Monitoring: Prometheus, Grafana, SIEM.

##### Be Detailed & Complete
- Every service folder: auth.ts middleware, modules/progress routes, AI engine worker if present.
- External dependencies: third-party AI service, email/SMS gateway if used.
- CI/CD workflow connecting to container registry → cloud environment.
- Don’t over-simplify; include the major pieces you see in file tree (scripts, Dockerfiles, tests).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Swimlanes
    subgraph "Clients" 
        direction TB
        MobileApp["Mobile App<br/>(Expo/React Native)"]:::client
        AdminPortal["Admin Portal<br/>(Next.js)"]:::client
        PWA["Desktop PWA<br/>(Planned)"]:::client
    end

    subgraph "API Layer"
        direction TB
        APIGateway["API Gateway<br/>(REST & GraphQL)"]:::api
    end

    subgraph "Services & Data Layer"
        direction TB
        subgraph "Business Services"
            direction TB
            AuthService["Auth Service<br/>(OAuth2/OIDC, JWT)"]:::service
            CoreAPI["Core API<br/>(Node/Express)"]:::service
            AIEngine["AI Engine<br/>(Learning-path generator)"]:::service
            AnalyticsHub["Analytics Hub<br/>(Real-time Analytics)"]:::service
        end
        subgraph "Data Stores"
            direction TB
            Postgres["PostgreSQL 16"]:::data
            TimeSeriesDB["Time Series DB<br/>(InfluxDB)"]:::data
            RedisCache["Redis<br/>(Cache/Session)"]:::data
        end
    end

    subgraph "Cross-cutting & Security"
        direction TB
        SecurityLayer["Security Layer<br/>(WAF, Rate Limiting)"]:::security
        LoggingMonitoring["Logging & Monitoring<br/>(Prometheus, Grafana, SIEM)"]:::security
    end

    subgraph "CI/CD & Infrastructure"
        direction TB
        CICD["GitHub Actions CI/CD"]:::infra
        DockerCompose["docker-compose.yml"]:::infra
        Dockerfiles["Service Dockerfiles"]:::infra
        StartupScripts["Startup Scripts"]:::infra
        IntegrationTests["Integration Tests"]:::infra
    end

    %% Connections
    MobileApp -->|"HTTPS requests"| APIGateway
    AdminPortal -->|"HTTPS requests"| APIGateway
    PWA -->|"HTTPS requests"| APIGateway

    APIGateway -->|"JWT validation"| AuthService
    APIGateway -->|"API calls"| CoreAPI

    CoreAPI -->|"RPC/HTTP"| AIEngine
    CoreAPI -->|"Event stream"| AnalyticsHub

    CoreAPI -->|Reads/Writes| Postgres
    AnalyticsHub -->|Writes metrics| TimeSeriesDB
    CoreAPI -->|Caches & sessions| RedisCache

    APIGateway -->|Protected by| SecurityLayer
    Postgres -->|Monitored by| LoggingMonitoring
    AIEngine -->|Monitored by| LoggingMonitoring
    AnalyticsHub -->|Monitored by| LoggingMonitoring

    CICD -->|Builds images| Dockerfiles
    CICD -->|Runs tests| IntegrationTests
    DockerCompose -->|Orchestrates| AdminPortal
    DockerCompose -->|Orchestrates| MobileApp
    DockerCompose -->|Orchestrates| CoreAPI

    %% Click Events
    click MobileApp "https://github.com/quartermasters/epaethicsapp/blob/main/mobile/App.tsx"
    click AdminPortal "https://github.com/quartermasters/epaethicsapp/tree/main/admin-portal/app"
    click APIGateway "https://github.com/quartermasters/epaethicsapp/blob/main/backend/src/server.ts"
    click AuthService "https://github.com/quartermasters/epaethicsapp/blob/main/backend/src/routes/auth.ts"
    click CoreAPI "https://github.com/quartermasters/epaethicsapp/blob/main/backend/src/routes/modules.ts"
    click AnalyticsHub "https://github.com/quartermasters/epaethicsapp/blob/main/backend/src/routes/progress.ts"
    click CICD "https://github.com/quartermasters/epaethicsapp/blob/main/.github/workflows/ci-cd.yml"
    click Dockerfiles "https://github.com/quartermasters/epaethicsapp/tree/main/admin-portal/Dockerfile"
    click Dockerfiles "https://github.com/quartermasters/epaethicsapp/tree/main/backend/Dockerfile"
    click Dockerfiles "https://github.com/quartermasters/epaethicsapp/tree/main/mobile/Dockerfile"
    click StartupScripts "https://github.com/quartermasters/epaethicsapp/blob/main/start-all.sh"
    click IntegrationTests "https://github.com/quartermasters/epaethicsapp/blob/main/tests/integration/system-tests.js"

    %% Styles
    classDef client fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px
    classDef api fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px
    classDef service fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px
    classDef data fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px
    classDef security fill:#f8d7da,stroke:#721c24,color:#721c24,stroke-width:1px
    classDef infra fill:#e2e3ff,stroke:#383f73,color:#383f73,stroke-width:1px
```
