# lagzenthakuri/flagforge architecture

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

- Interactive diagram: https://gitdiagram.com/lagzenthakuri/flagforge
- Repository: https://github.com/lagzenthakuri/flagforge

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Next.js App)" 
        direction TB
        FPMain["Pages (app/(main))"]:::frontend
        FPFot["Pages (app/(footer))"]:::frontend
        UIComp["Shared UI Components"]:::frontend
        ThemeCtx["React Context (Theme/Auth State)"]:::frontend
        AuthProv["Auth Provider (React)"]:::frontend
        Static["Static Assets"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Serverless Functions)"
        direction TB
        subgraph "Auth"
            direction TB
            NextAuth["NextAuth & Session Management"]:::api
            CheckAdmin["check-admin"]:::api
            CleanupTokens["cleanup-tokens"]:::api
            Logout["logout"]:::api
            ManualSignout["manual-signout"]:::api
            RevokeToken["revoke-token"]:::api
        end
        subgraph "Admin"
            direction TB
            AssignBadge["assign-badge"]:::api
            BadgeImages["badge-images"]:::api
            BadgeTemplates["badge-templates"]:::api
            DashboardStats["dashboard-stats"]:::api
            UploadBadge["upload-badge-image"]:::api
            AdminUsers["users"]:::api
        end
        subgraph "Problems"
            direction TB
            ProbList["route.ts"]:::api
            ProbId["[id]/route.ts"]:::api
            ProbHints["[id]/hints/route.ts"]:::api
            ProbCompleted["completed/route.ts"]:::api
        end
        subgraph "Badge Generation"
            direction TB
            BadgePNG["[username]/png/route.ts"]:::api
            BadgeSVG["[username]/svg/route.ts"]:::api
        end
        subgraph "Blogs"
            direction TB
            BlogsList["blogs/route.ts"]:::api
            BlogId["blogs/[id]/route.ts"]:::api
        end
        subgraph "Chat"
            direction TB
            ChatRoute["chat/route.ts"]:::api
            ChatStats["chat/stats/route.ts"]:::api
        end
        subgraph "Leaderboard"
            Leaderboard["leaderboard/route.ts"]:::api
        end
        subgraph "Resources"
            Resources["resources/route.ts"]:::api
        end
        subgraph "User"
            Profile["profile/route.ts"]:::api
            UserByName["user/[username]/route.ts"]:::api
            RecentSolved["user/recent-solved/route.ts"]:::api
        end
    end

    %% Database
    DB["MongoDB Database"]:::database

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleOAuth["Google OAuth"]:::external
        NotionAPI["Notion API"]:::external
        Statsig["Statsig"]:::external
        Discord["Discord Notifications"]:::external
    end

    %% Middleware
    subgraph "Middleware & Security"
        direction TB
        TokenBL["Token Blacklist"]:::middleware
        AdminGuard["Admin Guard"]:::middleware
    end

    %% Connections
    FPMain -->|uses| NextAuth
    FPFot -->|uses| NextAuth
    UIComp -->|renders UI| FPMain
    UIComp -->|renders UI| FPFot
    ThemeCtx -->|provides state| FPMain
    ThemeCtx -->|provides state| FPFot
    AuthProv -->|wraps app| FPMain
    AuthProv -->|wraps app| FPFot
    Static -->|assets| FPMain

    FPMain -->|HTTP| NextAuth
    FPMain -->|HTTP| CheckAdmin
    FPMain -->|HTTP| ProbList
    FPMain -->|HTTP| Leaderboard
    FPMain -->|HTTP| ChatRoute

    NextAuth -->|CRUD| DB
    CheckAdmin -->|CRUD| DB
    ProbList -->|CRUD| DB
    ProbId -->|CRUD| DB
    ProbHints -->|CRUD| DB
    ProbCompleted -->|CRUD| DB
    AssignBadge -->|CRUD| DB
    BadgeImages -->|CRUD| DB
    BadgeTemplates -->|CRUD| DB
    DashboardStats -->|CRUD| DB
    UploadBadge -->|CRUD| DB
    AdminUsers -->|CRUD| DB
    BadgePNG -->|CRUD| DB
    BadgeSVG -->|CRUD| DB
    BlogsList -->|CRUD| DB
    BlogId -->|CRUD| DB
    ChatRoute -->|CRUD| DB
    ChatStats -->|CRUD| DB
    Leaderboard -->|CRUD| DB
    Resources -->|CRUD| DB
    Profile -->|CRUD| DB
    UserByName -->|CRUD| DB
    RecentSolved -->|CRUD| DB

    API_LAYER --> DB
    NextAuth --> GoogleOAuth
    NextAuth -->|analytics| Statsig
    AssignBadge --> Discord
    ChatStats --> Statsig
    BlogsList --> NotionAPI

    FPMain --> TokenBL
    FPMain --> AdminGuard
    NextAuth --> TokenBL
    AssignBadge --> AdminGuard

    %% Click Events
    click FPMain "https://github.com/lagzenthakuri/flagforge/tree/mainv2/app/(main)"
    click FPFot "https://github.com/lagzenthakuri/flagforge/tree/mainv2/app/(footer)"
    click UIComp "https://github.com/lagzenthakuri/flagforge/tree/mainv2/components/"
    click ThemeCtx "https://github.com/lagzenthakuri/flagforge/blob/mainv2/context/ThemeContext.tsx"
    click AuthProv "https://github.com/lagzenthakuri/flagforge/blob/mainv2/providers/auth-provider.tsx"
    click Static "https://github.com/lagzenthakuri/flagforge/tree/mainv2/public/"
    click NextAuth "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/auth/[...nextauth]/route.ts"
    click CheckAdmin "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/auth/check-admin/route.ts"
    click CleanupTokens "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/auth/cleanup-tokens/route.ts"
    click Logout "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/auth/logout/route.ts"
    click ManualSignout "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/auth/manual-signout/route.ts"
    click RevokeToken "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/auth/revoke-token/route.ts"
    click AssignBadge "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/admin/assign-badge/route.ts"
    click BadgeImages "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/admin/badge-images/route.ts"
    click BadgeTemplates "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/admin/badge-templates/.../route.ts"
    click DashboardStats "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/admin/dashboard-stats/route.ts"
    click UploadBadge "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/admin/upload-badge-image/route.ts"
    click AdminUsers "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/admin/users/route.ts"
    click ProbList "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/problems/route.ts"
    click ProbId "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/problems/[id]/route.ts"
    click ProbHints "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/problems/[id]/hints/route.ts"
    click ProbCompleted "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/problems/completed/route.ts"
    click BadgePNG "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/badge/[username]/png/route.ts"
    click BadgeSVG "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/badge/[username]/svg/route.ts"
    click BlogsList "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/blogs/route.ts"
    click BlogId "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/blogs/[id]/route.ts"
    click ChatRoute "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/chat/route.ts"
    click ChatStats "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/chat/stats/route.ts"
    click Leaderboard "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/leaderboard/route.ts"
    click Resources "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/resources/route.ts"
    click Profile "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/profile/route.ts"
    click UserByName "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/user/[username]/route.ts"
    click RecentSolved "https://github.com/lagzenthakuri/flagforge/blob/mainv2/app/api/user/recent-solved/route.ts"
    click DB "https://github.com/lagzenthakuri/flagforge/tree/mainv2/models/"
    click DB "https://github.com/lagzenthakuri/flagforge/blob/mainv2/utils/db.ts"
    click TokenBL "https://github.com/lagzenthakuri/flagforge/blob/mainv2/middleware/tokenBlacklist.ts"
    click AdminGuard "https://github.com/lagzenthakuri/flagforge/blob/mainv2/middleware/adminToken.ts"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#004D40
    classDef api fill:#E8F5E9,stroke:#1B5E20,color:#2E7D32
    classDef database fill:#FFF3E0,stroke:#EF6C00,color:#E65100
    classDef external fill:#ECEFF1,stroke:#607D8B,color:#37474F
    classDef middleware fill:#FFEBEE,stroke:#C62828,color:#B71C1C
```
