# freecodecamp/exam-services architecture

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

- Interactive diagram: https://gitdiagram.com/freecodecamp/exam-services
- Repository: https://github.com/freecodecamp/exam-services

## Overview

##### Project type and purpose
- From the README and file tree, this is a small, single-service moderation microservice written in Rust. It’s part of a larger “Exam Services” suite, responsible for moderating exam attempts. It uses Prisma (Rust client) to talk to a relational database, and is deployed via Docker Compose on a DigitalOcean droplet. A cron job periodically triggers moderation tasks.

##### File structure
- Top-level
- .github/workflows/deploy.yaml → CI/CD pipeline
- docker-compose.yml → local and production service orchestration
- cron.staging & cron.production → host crontab entries
- moderation-service/ → main Rust microservice
- prisma/ → shared Rust library for Prisma client (DB access)
- moderation-service/
- src/main.rs → entry point
- src/lib.rs → core moderation logic
- src/db.rs → low-level database operations
- src/config.rs → env-based configuration
- src/attempt.rs → domain model for exam attempts
- Dockerfile & sample.env → containerization and env template
- tests/ → integration tests driving the nightly-Rust requirements
- prisma/
- src/lib.rs → auto-generated Prisma client for DB schema
- Cargo.toml → defines versioned Prisma dependency

##### README for additional insights
- Execution steps:
- `docker compose up -d` spins up moderation-service + database (Postgres)
- Cron files are loaded into the droplet’s crontab to schedule periodic moderation runs
- Deployment is fully automated via GitHub Actions (deploy.yaml) pushing to a DigitalOcean VM
- Testing requires seeding with freeCodeCamp exam data and running on Rust nightly

##### Main components & how they interact
a. Components
1. Developer/CI (GitHub Actions)
2. DigitalOcean Droplet (host)
3. Cron scheduler (on VM)
4. Docker Compose
– moderation-service container
– Postgres database container
5. Prisma client (Rust library inside moderation-service)
6. External caller (could be another service for seeding or API consumer)
b. Interactions
– Git pushes → GitHub Actions builds Docker images → SSH → Droplet → docker-compose deploy
– Cron (host) runs scheduled moderation commands (either HTTP calls or direct service CLI)
– moderation-service uses Prisma client to read/write exam/attempt records in Postgres
– Tests and local development mimic this stack via `docker compose up moderation`
c. Architectural patterns
– Microservice: single bounded context handling “moderation”
– Twelve-factor app: config via env, one service per container, logs to stdout
– CI/CD pipeline triggers deployments automatically
d. Key technologies
– Rust + Tokio (async) for the service
– Prisma Rust client for DB ORM
– Postgres as relational store
– Docker Compose for local/dev/production orchestration
– Cron for scheduled tasks
– GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Source Control & CI"
        Repo["GitHub Repo"]:::ci
        CI["GitHub Actions"]:::ci
    end
    Repo --> CI
    CI -->|"SSH & Deploy"| Host["DigitalOcean VM"]:::compute

    subgraph "DigitalOcean VM (Host)"
        subgraph "Cron Scheduler"
            CronProd["cron.production"]:::cron
            CronStaging["cron.staging"]:::cron
        end
        CronProd -->|"schedule task"| EntryPoint
        CronStaging -->|"schedule task"| EntryPoint

        subgraph "Docker Compose"
            DC["docker-compose.yml"]:::compose
            DC --> SvcContainer["moderation-service container"]:::service
            DC --> DB["Postgres"]:::db

            subgraph "moderation-service container"
                EntryPoint["src/main.rs (Entry)"]:::service
                Config["src/config.rs"]:::service
                Logic["src/lib.rs"]:::service
                Domain["src/attempt.rs"]:::service
                DBModule["src/db.rs"]:::service
                SvcSrc["Source: moderation-service/"]:::service
                Dockerfile["Dockerfile"]:::service
                Env["sample.env"]:::service
                Tests["tests/moderate.rs"]:::service

                EntryPoint --> Config
                Config --> Logic
                Logic --> Domain
                Domain --> DBModule
                DBModule --> DB
            end
        end
    end

    subgraph "Prisma Client Library"
        PrismaLib["prisma/src/lib.rs"]:::service
        PrismaToml["prisma/Cargo.toml"]:::service
    end
    PrismaLib --> DBModule

    subgraph "Project Files"
        RootToml["Cargo.toml"]:::doc
        GitIgnore[".gitignore"]:::doc
        License["LICENSE"]:::doc
        Readme["README.md"]:::doc
    end

    click CI "https://github.com/freecodecamp/exam-services/blob/main/.github/workflows/deploy.yaml"
    click DC "https://github.com/freecodecamp/exam-services/blob/main/docker-compose.yml"
    click CronProd "https://github.com/freecodecamp/exam-services/blob/main/cron.production"
    click CronStaging "https://github.com/freecodecamp/exam-services/blob/main/cron.staging"
    click SvcContainer "https://github.com/freecodecamp/exam-services/tree/main/moderation-service/"
    click EntryPoint "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/src/main.rs"
    click Logic "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/src/lib.rs"
    click Domain "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/src/attempt.rs"
    click Config "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/src/config.rs"
    click DBModule "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/src/db.rs"
    click Tests "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/tests/moderate.rs"
    click Dockerfile "https://github.com/freecodecamp/exam-services/tree/main/moderation-service/Dockerfile"
    click Env "https://github.com/freecodecamp/exam-services/blob/main/moderation-service/sample.env"
    click PrismaLib "https://github.com/freecodecamp/exam-services/blob/main/prisma/src/lib.rs"
    click PrismaToml "https://github.com/freecodecamp/exam-services/blob/main/prisma/Cargo.toml"
    click RootToml "https://github.com/freecodecamp/exam-services/blob/main/Cargo.toml"
    click GitIgnore "https://github.com/freecodecamp/exam-services/blob/main/.gitignore"
    click License "https://github.com/freecodecamp/exam-services/tree/main/LICENSE"
    click Readme "https://github.com/freecodecamp/exam-services/blob/main/README.md"

    classDef ci fill:#D0E6FF,stroke:#0366d6,color:#0366d6
    classDef compute fill:#E6FFE6,stroke:#00a000,color:#008000
    classDef compose fill:#CCFFCC,stroke:#00a000,color:#008000
    classDef service fill:#E8F4FF,stroke:#0064C8,color:#003d8c
    classDef db fill:#FFE6CC,stroke:#FF8C00,color:#CC7000
    classDef cron fill:#E6FFE6,stroke-dasharray:5 5,stroke:#00a000,color:#008000
    classDef doc fill:#F0F0F0,stroke:#999999,color:#333333
```
