# codenamed22/agora architecture

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

- Interactive diagram: https://gitdiagram.com/codenamed22/agora
- Repository: https://github.com/codenamed22/agora

## Overview

#### Purpose and Entry Points
ShardUp is a Next.js community platform for membership, applications, resources, events, learning programs, peer accountability, and competitive programming. The App Router is rooted at `app/layout.tsx` and `app/page.tsx`; public feature routes sit under `app/`, while authenticated flows use `app/(protected)/layout.tsx`. Operational endpoints are Auth.js at `app/api/auth/[...nextauth]/route.ts` and deployment health checks at `app/api/health/route.ts`.

#### Identity, Membership, and Authorization
Auth.js provides Google OAuth plus development-only login support, configured in `auth.ts` and exposed through `app/api/auth/[...nextauth]/route.ts`. Route/layout protection and server-side role/status decisions form the boundary between public visitors, applicants, active members, and admins: `app/(protected)/layout.tsx`, `lib/access.ts`, and `lib/guards.ts`. The join/application workflow enters at `app/(auth)/join/page.tsx`, is submitted through `app/(protected)/apply/actions.ts`, and is administered under `app/(protected)/admin/cohort/`.

#### Persistent Domain Layer
PostgreSQL is the system of record, accessed through Prisma’s shared client and adapter: `lib/prisma.ts`, `lib/prisma-adapter.ts`, and `prisma/schema.prisma`. Schema migrations encode evolving domains including applications/cohorts, events/RSVPs, profiles/badges, teaching boards, practice, contests, nudges, and notifications under `prisma/migrations/`. Domain services centralize query and mutation rules rather than leaving them solely in pages, notably `lib/members.ts`, `lib/events.ts`, and `lib/contest.ts`.

#### Community Content and Engagement
Public/member-facing sections expose directory profiles, badges, a curated bookshelf, events, notifications, and peer nudges. Primary route boundaries are `app/members/`, `app/badges/`, `app/bookshelf/`, `app/events/`, `app/notifications/`, and `app/nudges/`. Server actions mutate state close to route ownership—for example `app/events/actions.ts`, `app/notifications/actions.ts`, and `app/nudges/actions.ts`—with domain policy in `lib/events.ts`, `lib/notifications.ts`, and `lib/nudges.ts`. Event RSVP and contest registration are restricted to active members.

#### Learning, Teaching, and Collaborative Boards
The platform serves practice problems, structured design practice, masterclasses, and teaching sessions. Core routes are `app/practice/`, `app/problems/`, `app/masterclass/`, and `app/(protected)/admin/teaching/`; shared learning behavior lives in `lib/practice.ts` and `lib/teaching.ts`. Excalidraw-backed board views are mounted through `app/boards/[boardId]/page.tsx` and `app/boards/excalidraw-board.tsx`, with teaching/masterclass board routes providing contextual access.

#### Submission Judging and Contest Lifecycle
Practice and contest submissions flow from problem route actions—`app/problems/[slug]/actions.ts` and `app/contests/[slug]/actions.ts`—into a provider-abstracted judge: `lib/judge/index.ts`, `lib/judge/core.ts`, and `lib/judge/piston.ts`. The fake provider supports deterministic tests; production calls a separately self-hosted Piston API, authenticated by a reverse-proxy bearer key. Contest administration (`app/(protected)/admin/contests/actions.ts`) creates/publishes contests and finalizes standings/ratings; `lib/contest.ts` calculates scoring and ratings, publishes finalized problems into practice, and assigns tier badges.

#### Administration and Deployment Boundaries
Admins manage badges, cohorts, contests, events, problems, and teaching through `app/(protected)/admin/`; each domain owns server actions, e.g. `app/(protected)/admin/problems/actions.ts` and `app/(protected)/admin/contests/actions.ts`. Runtime deployment is Vercel/Next.js server functions backed by externally hosted PostgreSQL and Piston; local Postgres is defined in `docker-compose.yml`. Piston hosting guidance and bootstrap infrastructure are retained in `docs/oracle-piston.md` and `infra/oracle-piston-cloud-init.yaml`.

Main entry points: [`lib/prisma.ts`](https://github.com/codenamed22/agora/blob/main/lib/prisma.ts) (Prisma data access), [`app/problems/[slug]/actions.ts`](https://github.com/codenamed22/agora/blob/main/app/problems/%5Bslug%5D/actions.ts) (Problem & contest actions), [`lib/access.ts`](https://github.com/codenamed22/agora/blob/main/lib/access.ts) (Access guards), [`app/(protected)/layout.tsx`](https://github.com/codenamed22/agora/blob/main/app/(protected)/layout.tsx) (Protected layout)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity & Access"]
  node_protected["Protected layout<br/>Next.js layout<br/>[layout.tsx]"]
  node_auth{{"Auth.js<br/>identity provider<br/>[auth.ts]"}}
  node_auth_route["Auth endpoint<br/>route handler<br/>[route.ts]"]
  node_access{{"Access guards<br/>authorization<br/>[access.ts]"}}
end

subgraph group_community["Community Workflows"]
  node_public["Public routes<br/>Next.js routes"]
  node_applications["Join &amp; cohort workflow<br/>member onboarding<br/>[page.tsx]"]
  node_admin["Admin operations<br/>admin routes"]
  node_engagement["Community engagement<br/>feature routes"]
  node_event_service{{"Engagement services<br/>domain services<br/>[events.ts]"}}
end

subgraph group_learning["Learning &amp; Competition"]
  node_practice["Practice &amp; masterclasses<br/>learning routes"]
  node_teaching["Teaching administration<br/>admin learning routes"]
  node_boards["Collaborative boards<br/>Excalidraw view<br/>[page.tsx]"]
  node_submissions["Problem &amp; contest actions<br/>server actions<br/>[actions.ts]"]
  node_judge{{"Judge abstraction<br/>submission judging<br/>[index.ts]"}}
  node_contest_service{{"Contest lifecycle<br/>domain service<br/>[contest.ts]"}}
end

subgraph group_platform["Data &amp; Runtime"]
  node_piston{{"Self-hosted Piston<br/>code execution API"}}
  node_prisma{{"Prisma data access<br/>ORM client<br/>[prisma.ts]"}}
  node_postgres[("PostgreSQL<br/>system of record<br/>[schema.prisma]")]
  node_health["Health endpoint<br/>route handler<br/>[route.ts]"]
end

node_public -->|"join"| node_applications
node_auth_route -->|"uses"| node_auth
node_auth -->|"adapter"| node_prisma
node_protected -->|"enforces"| node_access
node_access -->|"checks roles and status"| node_prisma
node_applications -->|"submits application"| node_protected
node_admin -->|"admin authorization"| node_access
node_admin -->|"manages domains"| node_prisma
node_engagement -->|"actions and policy"| node_event_service
node_event_service -->|"persists engagement"| node_prisma
node_practice -->|"submits solutions"| node_submissions
node_teaching -->|"contextual access"| node_boards
node_practice -->|"masterclass access"| node_boards
node_submissions -->|"judges code"| node_judge
node_submissions -->|"registration and scoring"| node_contest_service
node_judge -->|"production provider"| node_piston
node_contest_service -->|"standings, ratings, badges"| node_prisma
node_prisma -->|"reads and writes"| node_postgres
node_health -.->|"checks availability"| node_postgres

click node_protected "https://github.com/codenamed22/agora/blob/main/app/(protected)/layout.tsx"
click node_auth "https://github.com/codenamed22/agora/blob/main/auth.ts"
click node_auth_route "https://github.com/codenamed22/agora/blob/main/app/api/auth/%5B...nextauth%5D/route.ts"
click node_access "https://github.com/codenamed22/agora/blob/main/lib/access.ts"
click node_applications "https://github.com/codenamed22/agora/blob/main/app/(auth)/join/page.tsx"
click node_event_service "https://github.com/codenamed22/agora/blob/main/lib/events.ts"
click node_boards "https://github.com/codenamed22/agora/blob/main/app/boards/%5BboardId%5D/page.tsx"
click node_submissions "https://github.com/codenamed22/agora/blob/main/app/problems/%5Bslug%5D/actions.ts"
click node_judge "https://github.com/codenamed22/agora/blob/main/lib/judge/index.ts"
click node_contest_service "https://github.com/codenamed22/agora/blob/main/lib/contest.ts"
click node_prisma "https://github.com/codenamed22/agora/blob/main/lib/prisma.ts"
click node_postgres "https://github.com/codenamed22/agora/blob/main/prisma/schema.prisma"
click node_health "https://github.com/codenamed22/agora/blob/main/app/api/health/route.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_protected,node_auth,node_auth_route,node_access toneBlue
class node_public,node_applications,node_admin,node_engagement,node_event_service toneAmber
class node_practice,node_teaching,node_boards,node_submissions,node_judge,node_contest_service toneMint
class node_piston,node_prisma,node_postgres,node_health toneRose
```

## Components

### Identity & Access

- [Protected layout](https://github.com/codenamed22/agora/blob/main/app/(protected)/layout.tsx): Next.js layout · Authenticated member and admin route boundary. · `app/(protected)/layout.tsx`
- [Auth.js](https://github.com/codenamed22/agora/blob/main/auth.ts): identity provider · Google OAuth and development login configuration. · `auth.ts`
- [Auth endpoint](https://github.com/codenamed22/agora/blob/main/app/api/auth/%5B...nextauth%5D/route.ts): route handler · `app/api/auth/[...nextauth]/route.ts`
- [Access guards](https://github.com/codenamed22/agora/blob/main/lib/access.ts): authorization · Enforces role and membership-status decisions. · `lib/access.ts`

### Community Workflows

- **Public routes**: Next.js routes · Marketing and public community entry points.
- [Join & cohort workflow](https://github.com/codenamed22/agora/blob/main/app/(auth)/join/page.tsx): member onboarding · Applications are submitted by members and reviewed by admins. · `app/(auth)/join/page.tsx`
- **Admin operations**: admin routes · Manages cohorts, badges, events, problems, contests, and teaching.
- **Community engagement**: feature routes · Members, badges, bookshelf, events, notifications, and nudges.
- [Engagement services](https://github.com/codenamed22/agora/blob/main/lib/events.ts): domain services · Applies event, notification, and nudge policy. · `lib/events.ts`

### Learning & Competition

- **Practice & masterclasses**: learning routes · Practice problems, design practice, and masterclass experiences.
- **Teaching administration**: admin learning routes
- [Collaborative boards](https://github.com/codenamed22/agora/blob/main/app/boards/%5BboardId%5D/page.tsx): Excalidraw view · Board views are linked from teaching and masterclass contexts. · `app/boards/[boardId]/page.tsx`
- [Problem & contest actions](https://github.com/codenamed22/agora/blob/main/app/problems/%5Bslug%5D/actions.ts): server actions · Accepts practice submissions and contest registrations. · `app/problems/[slug]/actions.ts`
- [Judge abstraction](https://github.com/codenamed22/agora/blob/main/lib/judge/index.ts): submission judging · Selects deterministic fake or production execution providers. · `lib/judge/index.ts`
- [Contest lifecycle](https://github.com/codenamed22/agora/blob/main/lib/contest.ts): domain service · Scores contests, updates ratings, awards tiers, and publishes practice problems. · `lib/contest.ts`

### Data & Runtime

- **Self-hosted Piston**: code execution API · Production judge backend protected by reverse-proxy bearer authentication.
- [Prisma data access](https://github.com/codenamed22/agora/blob/main/lib/prisma.ts): ORM client · Shared PostgreSQL client and Auth.js adapter. · `lib/prisma.ts`
- [PostgreSQL](https://github.com/codenamed22/agora/blob/main/prisma/schema.prisma): system of record · Stores membership, content, learning, contest, and notification domains. · `prisma/schema.prisma`
- [Health endpoint](https://github.com/codenamed22/agora/blob/main/app/api/health/route.ts): route handler · Deployment health check. · `app/api/health/route.ts`

## Connections

- Public routes → Join & cohort workflow: join
- Auth endpoint → Auth.js: uses
- Auth.js → Prisma data access: adapter
- Protected layout → Access guards: enforces
- Access guards → Prisma data access: checks roles and status
- Join & cohort workflow → Protected layout: submits application
- Admin operations → Access guards: admin authorization
- Admin operations → Prisma data access: manages domains
- Community engagement → Engagement services: actions and policy
- Engagement services → Prisma data access: persists engagement
- Practice & masterclasses → Problem & contest actions: submits solutions
- Teaching administration → Collaborative boards: contextual access
- Practice & masterclasses → Collaborative boards: masterclass access
- Problem & contest actions → Judge abstraction: judges code
- Problem & contest actions → Contest lifecycle: registration and scoring
- Judge abstraction → Self-hosted Piston: production provider
- Contest lifecycle → Prisma data access: standings, ratings, badges
- Prisma data access → PostgreSQL: reads and writes
- Health endpoint → PostgreSQL: checks availability