How lagzenthakuri/flagforge works
Project Type and Purpose
• This is a full-stack web application—a Capture The Flag (CTF) platform—built with Next.js (app router) on the frontend and using Next.js API routes as the backend. It provides an interface for users to browse problems, submit flags, track progress, view leaderboards, and for admins to manage challenges and badges.
File Structure
• Top-level “app/” folder: contains both UI pages (React components in app/(main) and app/(footer)) and serverless API routes under app/api/.
• “components/”, “providers/”, “context/”: React UI primitives, global context (theme/auth), and higher-order wrappers.
• “models/”: MongoDB schemas & TypeScript models.
• “utils/” and “lib/”: database connection logic, authentication utilities, token blacklist, Discord notifications, difficulty calculator.
• “middleware/”: Express-style middleware for token blacklisting and admin-only routes.
• Config files: next.config.mjs, tsconfig.json, tailwind.config.ts, postcss.config.js.
README for Additional Insights
• Uses MongoDB for persistence.
• NextAuth + Google OAuth + custom token blacklist for authentication.
• External integrations: Notion API for content, Statsig for feature flags or analytics, Discord notifications.
• Hosted via Vercel or similar (serverless functions).
Main Components and Their Relationships
a. Frontend (UI Layer)
• Next.js app pages (app/(main), app/(footer)) and shared UI components.
• React Context & Providers for theme and authentication state.
• Static assets under public/.
b. Backend (API Layer)
• Next.js API Routes under app/api/ organized by domain (auth, admin, badge, blogs, problems, chat, leaderboard, resources, user).
• Each route uses utils/db to connect to MongoDB and models/ to read/write data.
• NextAuth (app/api/auth) for session management; middleware enforces token blacklist and admin checks.
c. Database
• MongoDB hosting collections defined by models/*.
• Connection pooling and utils/db.
d. External Services
• Notion API (content management)
• Google OAuth (via NextAuth)
• Statsig (feature flags/analytics)
• Discord (notifications)
e. Middleware & Security
• Token blacklist to revoke sessions (middleware/tokenBlacklist).
• AdminToken middleware protecting admin API endpoints.
Architectural Patterns and Design Principles
• Monolithic Next.js application with clear separation: UI vs. API vs. Data models.
• “MVC-like” pattern: pages = Views, API routes = Controllers, models = Data layer.
• Serverless functions (one route handler per file).
• Context and Provider pattern for React state.
• Middleware layer for cross-cutting concerns (auth, admin).
a. Components and Layers
b. Relationships & Data Flow
c. Call out Architectural Patterns
• “React Context” around shared state.
• “Middleware” before protected Admin routes.
d. Relevant Technologies
• Next.js (App Router), React, Tailwind CSS on UI.
• Node.js, Next.js API Routes on backend.
• MongoDB, Mongoose for data persistence.
• NextAuth, JWT, token blacklist for auth.
• External: Google OAuth, Notion, Statsig, Discord.