# skkuding/codedang architecture

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

- Interactive diagram: https://gitdiagram.com/skkuding/codedang
- Repository: https://github.com/skkuding/codedang

## Overview

##### Project type and purpose
- This is a cloud-native, full-stack online judge system (“Codedang”) comprised of:
- A Next.js front-end (apps/frontend) serving both student (client) and admin dashboards
- A NestJS GraphQL back-end (apps/backend) handling business logic, authentication, and data access via Prisma
- An independent Go judge service “Iris” (iris/) that compiles and runs submitted code in sandboxes
- Supporting libraries (apps/backend/libs and apps/frontend/libs) for shared auth, caching, and utilities
- Infrastructure-as-code (apps/infra/) that provisions AWS ECS, RDS, Redis, S3, CloudFront, VPC, and a RabbitMQ queue

##### File structure
- Top-level directories reveal separation of concerns:
- apps/frontend – Next.js App Router, handlers for NextAuth, GraphQL codegen, Playwright tests
- apps/backend – NestJS monorepo with “admin” and “client” GraphQL sub-apps, shared libs, Prisma schema, migrations
- iris – standalone Go microservice interacting with RabbitMQ, S3, Postgres, providing judge/sandbox logic
- apps/infra – Terraform configs for “production”, “stage”, and “rc” environments, each deploying ECS services (admin_api, client_api, iris), network, storage, and autoscaling modules

##### Read the README for additional insights
- Confirms it’s an Online Judge system aimed at lowering the barrier for new coders, with compile+run+judge fully online.
- Documentation and contributing guides link to an external docs site.

##### Main components & interactions (
a. Frontend (Next.js)
- Student UI and Admin UI served by Vercel or ECS behind CloudFront
- NextAuth handler for OAuth/JWT flows
- Apollo Client connects over GraphQL to back-end
b. Backend (NestJS GraphQL)
- “client” and “admin” GraphQL endpoints
- Auth guards (JWT, OAuth) via libs/auth
- Business services (User, Contest, Assignment, Submission, Notice, Group)
- Data layer: Prisma + PostgreSQL, plus Redis cache via libs/cache
- File storage: media and testcases in S3 via storage service
- Publishes judge requests to RabbitMQ
c. Judge Service (Iris – Go)
- Consumes messages from RabbitMQ
- Loads testcases from S3 or Postgres
- Executes code in sandbox (e.g., container or chroot)
- Produces results back to queue or directly calls back GraphQL endpoint
d. Infrastructure (AWS via Terraform)
- VPC with public/private subnets, Route53, CloudFront, ACM TLS
- ECS Fargate clusters for frontend (if self-hosted), backend, iris, and IRIS
- RDS (PostgreSQL) for primary data
- Elasticache (Redis) for cache
- S3 buckets for media, problem testcases, and sample files
- RabbitMQ or SQS (message_queue.tf) for judge requests
- Load balancers and autoscaling modules

##### Architectural patterns & design principles
- Separation of concerns: distinct UI, API, and worker tiers
- Modular monorepo: shared libraries for auth, exception handling, logging, pipes, Prisma module
- Event-driven microservice: judge requests via message queue decoupling the API and compute
- Infrastructure-as-code for repeatable environments (prod, stage, rc) with Terraform modules

##### Essential details to capture
- Separate student and admin frontends (they share Next.js but different paths/components)
- The two GraphQL sub-applications within NestJS (“client” & “admin”) and their shared libs
- The judge worker’s sandbox steps and policy module (Java, C++ support)
- Terraform modules for VPC, ECS, Auto-scaling, Load Balancing
- Security boundaries: JWT/OAuth guards; IAM roles for S3 and ECS tasks
- CI/CD workflows (GitHub Actions) that build, test, and deploy each layer

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Edge Services
    Route53["Route53"]:::cloud
    CloudFront["CloudFront CDN"]:::cloud
    Route53 --> CloudFront

    %% VPC Boundary
    subgraph "VPC" 
        direction TB

        %% Presentation Tier
        subgraph "Presentation Tier"
            direction TB
            Browser["Web Browser"]:::ui
            Browser -->|"HTTPS"| CloudFront
            CloudFront -->|"Requests"| NextjsFE
            NextjsFE["Next.js Frontend"]:::ui
            NextAuth["NextAuth Handler"]:::ui
            NextjsFE -->|"Auth"| NextAuth
            Codegen["GraphQL Codegen & Schema"]:::ui
            SharedFE["Shared FE Libraries"]:::ui
            Tests["Playwright E2E Tests"]:::ui
        end

        %% API Tier
        subgraph "API Tier"
            direction TB
            GraphQLAPI["GraphQL API (NestJS)"]:::api
            subgraph "Sub-Apps"
                direction TB
                AdminAPI["Admin API"]:::api
                ClientAPI["Client API"]:::api
            end
            subgraph "Shared Backend Libs"
                direction TB
                AuthLib["Auth Lib"]:::api
                CacheLib["Cache Lib"]:::api
                PrismaLib["Prisma Lib"]:::api
                ExceptionLib["Exception Lib"]:::api
                LoggerLib["Logger Lib"]:::api
                PipeLib["Pipe Lib"]:::api
                ConstLib["Constants Lib"]:::api
                TypesLib["Types Lib"]:::api
            end
            GraphQLAPI --> AdminAPI
            GraphQLAPI --> ClientAPI
            GraphQLAPI --> AuthLib
            GraphQLAPI --> CacheLib
            GraphQLAPI --> PrismaLib
            GraphQLAPI --> ExceptionLib
            GraphQLAPI --> LoggerLib
            GraphQLAPI --> PipeLib
            GraphQLAPI --> ConstLib
            GraphQLAPI --> TypesLib
        end

        %% Processing Tier
        subgraph "Processing Tier"
            direction TB
            Iris["Judge Service (Iris)"]:::worker
            AdminAPI -->|"Enqueue Judge"| RabbitMQ
            ClientAPI -->|"Enqueue Judge"| RabbitMQ
            RabbitMQ["RabbitMQ Queue"]:::datastore
            RabbitMQ -->|"Consume"| Iris
        end

        %% Data Tier
        subgraph "Data Tier"
            direction TB
            Postgres["PostgreSQL"]:::datastore
            Redis["Redis Cache"]:::datastore
            S3["S3 (Media & Testcases)"]:::cloud
        end

        %% Flows between API and Data
        GraphQLAPI -->|"SQL Queries"| Postgres
        GraphQLAPI -->|"Cache Ops"| Redis
        GraphQLAPI -->|"S3 Ops"| S3
        Iris -->|"Fetch Testcases"| S3
        Iris -->|"Store Results"| Postgres
        Iris -->|"Publish Results"| RabbitMQ
        RabbitMQ -->|"Notify API"| GraphQLAPI
    end

    %% Click Events
    click NextjsFE "https://github.com/skkuding/codedang/tree/main/apps/frontend"
    click NextAuth "https://github.com/skkuding/codedang/blob/main/apps/frontend/app/(handler)/next-auth/api/auth/[...nextauth]/route.ts"
    click Codegen "https://github.com/skkuding/codedang/blob/main/apps/frontend/codegen.ts"
    click Codegen "https://github.com/skkuding/codedang/blob/main/apps/frontend/schema.graphql"
    click SharedFE "https://github.com/skkuding/codedang/tree/main/apps/frontend/libs"
    click Tests "https://github.com/skkuding/codedang/tree/main/apps/frontend/playwright/tests"
    click GraphQLAPI "https://github.com/skkuding/codedang/tree/main/apps/backend"
    click AdminAPI "https://github.com/skkuding/codedang/tree/main/apps/backend/apps/admin/src"
    click ClientAPI "https://github.com/skkuding/codedang/tree/main/apps/backend/apps/client/src"
    click AuthLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/auth"
    click CacheLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/cache"
    click PrismaLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/prisma"
    click ExceptionLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/exception"
    click LoggerLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/logger"
    click PipeLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/pipe"
    click ConstLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/constants"
    click TypesLib "https://github.com/skkuding/codedang/tree/main/apps/backend/libs/types"
    click Iris "https://github.com/skkuding/codedang/tree/main/iris"
    click Iris "https://github.com/skkuding/codedang/tree/main/iris/src"
    click Iris "https://github.com/skkuding/codedang/tree/main/iris/Dockerfile"
    click Iris "https://github.com/skkuding/codedang/blob/main/iris/entrypoint.sh"
    click Postgres "https://github.com/skkuding/codedang/blob/main/apps/backend/prisma/schema.prisma"
    click Postgres "https://github.com/skkuding/codedang/tree/main/apps/backend/prisma/migrations"
    click RubyInfraProd "https://github.com/skkuding/codedang/tree/main/apps/infra/production"
    click RubyInfraRC "https://github.com/skkuding/codedang/tree/main/apps/infra/rc"
    click RubyInfraStage "https://github.com/skkuding/codedang/tree/main/apps/infra/stage"

    %% Styles
    classDef ui fill:#9f6,stroke:#333,stroke-width:1px
    classDef api fill:#6cf,stroke:#333,stroke-width:1px
    classDef worker fill:#f96,stroke:#333,stroke-width:1px
    classDef datastore fill:#ccc,stroke:#333,stroke-width:1px
    classDef cloud fill:#ace,stroke:#333,stroke-width:1px
```
