codenamed22/agora

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.