Codu

Full-stack web app with a Next.js frontend, Spring Boot API, and a worker for background code execution.

Architecture

┌──────────────┐       ┌──────────────┐       ┌──────────────┐
│   Frontend   │──────▶│   Backend    │──────▶│  PostgreSQL  │
│  (Next.js)   │◀──────│ (Spring Boot)│       │    (RDS)     │
└──────────────┘       └──────────────┘       └──────────────┘
       │                      ▲
       │ SockJS/STOMP         │ WebSocket
       ▼                      │
┌──────────────┐              │
│   Browser    │──────────────┘
└──────────────┘

┌──────────────┐  submissions  ┌──────────────┐       ┌──────────────┐
│   Backend    │──────SQS─────▶│ Code Runner  │──────▶│   Docker     │
│              │◀─────SQS──────│   (Worker)   │       │  (Sandbox)   │
└──────────────┘   results     └──────────────┘       └──────────────┘

Services:

• Frontend: Next.js 16, React 19, TanStack Query
• Backend: Spring Boot 3.5, Java 21, Spring AI
• Code Runner: Docker-in-Docker sandbox execution
• Database: PostgreSQL 16 (58 tables, Flyway migrations)
• Messaging: AWS SQS (2 queues: submissions, results)
• WebSocket: SockJS + STOMP (notifications, chat, live results)

Features

• Next.js frontend and Spring Boot 3
• Auth with JWT, refresh tokens, OAuth (Google/GitHub), and password reset flow
• User profiles with achievements, levels, streaks, and localization data
• Courses with modules, lessons, and tasks (including programming tasks)
• Built-in code runner with test cases and async result processing
• Learning sessions, activity tracking, analytics charts, and progress dashboards
• AI mentor chat powered by Spring AI (OpenAI)
• Forum posts, comments, categories, and reporting
• Groups/clans with join requests, rankings, and group chat
• Direct messages, typing indicators, read receipts, and conversation list
• Notifications center with preferences and WebSocket delivery
• Moderation tools: reports, blocks, and moderation logs
• Subscriptions and payments via Stripe + webhook handling
• Admin course tooling and subscription product management
• Affiliate links and newsletter subscriptions
• SQS-based background jobs (LocalStack in dev)

Run locally (Docker)

1. Copy .env.example to .env and fill in the values.
2. Start the stack:

   docker compose --profile local up --build

3. Open the app at http://localhost:3000 (API at http://localhost:8080).

Database

• Database is PostgreSQL (local Docker service postgres).
• Schema migrations are managed with Flyway in backend/src/main/resources/db/migration.
• Optional seed data lives in backend/src/main/resources/db-scripts/insert-table.sql.
• After migrations complete, load seed data so the app is not empty:

  ./backend/seed-db.sh

• Indexes and extensions are created in backend/src/main/resources/db/migration/V50__create_indexes.sql (includes pg_trgm, GIN, and BRIN indexes for search and activity feeds).
• Schema diagram: backend/src/main/resources/db/diagram/db_diagram_28_12_2025.png.
• Migrations currently define 58 tables.
• Production runs on AWS RDS with automated backups.

Code Runner

Isolated code execution service that runs user submissions in sandboxed Docker containers:

• Sandbox: Docker containers with network disabled, all capabilities dropped, memory/CPU/PID limits
• Queue: SQS-based async processing (LocalStack in dev)
• Languages: Java 21 (Corretto)
• Security: 10s timeout, 128MB memory, no-new-privileges

See code-runner/README.md for architecture details.

Feature notes

This section will be extended as remaining functionality is merged.

User

• Registration/login (email or OAuth), JWT session handling, and refresh tokens
• Editable profile with bio, avatar, localization, and stats
• Leveling, streaks, and XP-based progression

Achievements

• Achievement catalog with user progress tracking
• Profile showcase for earned achievements and milestones

Affiliate links

• Per-user affiliate link generation using NanoID
• Shareable links tied to user profiles

Friends

• Friend requests and acceptance flow
• Direct messages with read indicators

Groups

• Create and manage groups/clans with short names and avatars
• Join requests, member lists, and group chat
• Rankings and activity views for groups

Leaderboards

• Global and group rankings based on points
• Top users/groups snapshots for competitive views and highlights
• Refreshed every 30 minutes by a scheduled backend job

Payments

• Stripe Checkout for subscriptions and token packs
• Webhook handling for lifecycle events and payment status sync

Learning

• Courses built from modules, lessons, and tasks with progress tracking
• Spaced-repetition tests and scheduled reminders

Moderation and admin

• Moderation tools for reports, blocks, and audit logs
• Admin panels for course structure and subscription product management

Forum

• Topic categories, posts, and threaded comments
• Reporting flow integrated with moderation

Tests

Component	Framework	Command
Backend	Spock (Groovy)	mvn -B -f backend/pom.xml test
Backend Integration	Testcontainers	mvn -B -f backend/pom.xml verify
Code Runner	Spock	mvn -B -f code-runner/pom.xml test
Frontend E2E	Playwright	npm run test:e2e (in frontend/)

CI

GitHub Actions runs 6 workflows:

Workflow	Trigger	Description
frontend.yml	Push/PR to main	npm install, lint, build (Node 20)
backend-tests.yml	Backend changes	Unit + integration tests (JDK 21)
code-runner-tests.yml	Code-runner changes	Unit tests
e2e-tests.yml	PR to main	Full E2E with Docker Compose
build.yml	Push/PR	Build verification
secret-scanning.yml	Push/PR to main	Gitleaks scan

Monitoring

Optional Prometheus + Grafana stack in monitoring/:

docker compose --profile monitoring up

• Prometheus: http://localhost:9090 - scrapes /actuator/prometheus
• Grafana: http://localhost:3001 - dashboards

Environment:

GRAFANA_ADMIN_USER=codu_admin
GRAFANA_ADMIN_PASSWORD=codu_admin_pass

Deployment

Production runs on AWS:

Component	Service
Frontend	AWS Amplify
Backend API	EC2 (Docker)
Code Runner	EC2 (Docker + DinD)
Database	RDS PostgreSQL
Message Queues	SQS (2 queues: submissions, results)
Email	SES