# kodeinkgp-technology-web-3-0-society/kik-nextjs architecture

> Architecture diagram of the GitHub repository kodeinkgp-technology-web-3-0-society/kik-nextjs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kodeinkgp-technology-web-3-0-society/kik-nextjs
- Repository: https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs

## Overview

1. **Overall shape**
   - This is a **Next.js App Router** site for the KodeinKGP student society.
   - The repository combines a public marketing/content site with several interactive subsystems: **deKodeX**, **PDS practice/lab**, **articles**, **events**, **leaderboard**, **auth/registration**, and **team pages**.

2. **Front-end composition**
   - UI is split between `src/Components/` and route-level page files under `src/app/`.
   - `src/Components/` holds reusable presentation blocks such as the navbar, footer, landing sections, auth forms, loaders, buttons, cards, and deKodeX-specific UI.
   - `src/app/` provides the actual routed screens and stitches those components together.

3. **Routing and page boundaries**
   - The top-level routes include landing/home, articles, events, teams, tech-triad, auth, registration, summary, leaderboard, PDS, and deKodeX.
   - Dynamic routes are used where content is indexed by an identifier, especially:
     - `src/app/dekodeX/[QuestionID]/`
     - `src/app/leaderboard/[page]/`
     - `src/app/pds/lab/[topic]/[subTopic]/[ind]/`
   - This indicates a content-driven UI where each route is backed by structured data rather than hardcoded screens.

4. **deKodeX challenge system**
   - `src/app/dekodeX/` is the most application-like subsystem.
   - It includes a problem arena, modal dialogs, leaderboard view, per-question pages, and loading states.
   - Supporting API routes handle the challenge lifecycle: **auth**, **question retrieval**, **submission**, **leaderboard**, **Turnstile verification**, and **certificate issuance/checking**.

5. **Backend boundary and external services**
   - `src/backend/firebase.js` and `src/backend/firebaseAdmin.js` show a split between **client Firebase usage** and **server/admin Firebase access**.
   - `requireAuth.js` and `middleware.js` suggest route-level protection for authenticated flows.
   - The use of Cloudflare Turnstile is explicit via `verifyTurnstile`, indicating bot protection on sensitive endpoints like submission/auth.

6. **Data model and content sources**
   - Much of the site is data-driven from JSON and static files in `src/data/` and `public/data/`.
   - `src/data/` contains curated content for articles, events, teams, animations, and PDS question banks.
   - `public/data/` and `public/testcases.json` appear to store challenge inputs, outputs, or downloadable artifacts used by deKodeX/PDS features.
   - This means the app often renders from local structured content instead of a remote CMS.

7. **PDS subsystem**
   - `src/app/pds/` is a separate learning/practice area with theory and lab sections.
   - The lab section is hierarchical and topic/subtopic-driven, with components for lab cards, questions, subtopics, and a login modal.
   - This subsystem likely serves problem-solving content from local JSON question banks and is distinct from deKodeX in both UX and content structure.

8. **Articles and media**
   - `src/app/articles/` and `public/article` support article browsing with animation wrappers and related data files.
   - The project uses **Lottie** animations heavily, with JSON assets in `src/data/animations/` and article-specific animation metadata in `src/data/articles/`.
   - Static images for events and articles are stored under `public/`, keeping rich media separate from code.

9. **Authentication and user state**
   - `src/app/auth/` and `src/Components/Auth/` implement sign-in/sign-up UI.
   - `src/contexts/authContext.jsx` plus `src/hooks/useAuthToken.js` indicate shared client-side auth state and token handling.
   - `src/backend/requireAuth.js` and protected API routes show that auth is enforced both in the UI and on the server side.

10. **Operational tooling and migration**
   - The `backup/` folder contains a Firestore migration script, suggesting an earlier or ongoing data migration path.
   - `src/backend/runtimeCache.js` implies server-side caching for performance or rate-sensitive lookups.
   - `netlify.toml` shows the app is intended to deploy on **Netlify**, even though it is built with Next.js.

11. **Styling and build setup**
   - Styling uses **Tailwind CSS** with supporting PostCSS and global CSS.
   - `next.config.mjs`, `tailwind.config.js`, and `eslint.config.mjs` define the build/runtime and code-quality boundaries.
   - The codebase is organized as a typical Next.js application with static assets in `public/`, app routes in `src/app/`, and shared logic in `src/backend/` and `src/contexts/`.

12. **How data flows through the system**
   - Static content and JSON are loaded into route components for most public pages.
   - Interactive features such as deKodeX and auth move through API routes, which then access Firebase/admin services and return computed state such as validation, submissions, leaderboard data, or certificates.
   - The architecture is therefore a mix of **static content delivery** and **server-backed interactive workflows** centered around Firebase.

Main entry points: [`src/app/dekodeX/api/auth/route.js`](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/api/auth/route.js) (deKodeX API), [`src/app/layout.jsx`](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/layout.jsx) (Root Layout), [`src/app/page.jsx`](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/page.jsx) (Home), [`src/app/pds/page.jsx`](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/page.jsx) (PDS Home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App Shell"]
  node_layout["Root Layout<br/>app shell<br/>[layout.jsx]"]
end

subgraph group_public["Public Site"]
  node_home["Home<br/>landing route<br/>[page.jsx]"]
  node_articles["Articles<br/>content route<br/>[page.jsx]"]
  node_events["Events<br/>content route<br/>[page.jsx]"]
  node_teams["Teams<br/>directory route<br/>[page.jsx]"]
  node_techtriad["Tech Triad<br/>content route<br/>[page.jsx]"]
end

subgraph group_dekodex["deKodeX"]
  node_dekodexhome["deKodeX Home<br/>challenge hub<br/>[page.jsx]"]
  node_problemarena["Problem Arena<br/>challenge ui<br/>[ProblemArena.jsx]"]
  node_questionpage["Question Page<br/>dynamic route<br/>[page.jsx]"]
  node_leaderboardpage["Leaderboard<br/>paginated route<br/>[page.jsx]"]
  node_dekodexapi["deKodeX API<br/>api routes<br/>[route.js]"]
end

subgraph group_pds["PDS"]
  node_pdsroot["PDS Home<br/>practice route<br/>[page.jsx]"]
  node_pdslab["PDS Lab<br/>lab hub<br/>[page.jsx]"]
  node_pdstheory["PDS Theory<br/>theory route<br/>[page.jsx]"]
end

subgraph group_platform["Platform"]
  node_navbar["Navbar<br/>shared ui<br/>[navbar.jsx]"]
  node_landing["Landing<br/>section ui<br/>[landing.jsx]"]
  node_footer["Footer<br/>shared ui<br/>[footer.jsx]"]
  node_authpage["Auth Page<br/>auth route<br/>[page.jsx]"]
  node_regform["Registration<br/>form route<br/>[page.jsx]"]
  node_regsummary["Summary<br/>[page.jsx]"]
  node_authctx["Auth Context<br/>state management<br/>[authContext.jsx]"]
  node_firebase["Firebase Client<br/>client backend<br/>[firebase.js]"]
  node_firebaseadmin["Firebase Admin<br/>server backend<br/>[firebaseAdmin.js]"]
  node_requireauth["Require Auth<br/>guard<br/>[requireAuth.js]"]
  node_turnstile["Turnstile Verify<br/>security api<br/>[route.js]"]
end

subgraph group_content["Content Data"]
  node_articlesdata["Articles Data<br/>content json<br/>[articles-data.json]"]
  node_eventsdata["Events Data<br/>content json<br/>[EventsData.json]"]
  node_teamsdata["Teams Data<br/>content json<br/>[content.json]"]
  node_qna["Question Banks<br/>json content<br/>[lab-questions.json]"]
  node_dekodexdata["Challenge Data<br/>content json<br/>[event-que.json]"]
end

node_layout -->|"wraps"| node_home
node_layout -->|"routes"| node_articles
node_layout -->|"routes"| node_events
node_layout -->|"routes"| node_teams
node_layout -->|"routes"| node_dekodexhome
node_layout -->|"routes"| node_pdsroot
node_home -->|"uses"| node_navbar
node_home -->|"uses"| node_landing
node_home -->|"uses"| node_footer
node_articles -->|"reads"| node_articlesdata
node_events -->|"reads"| node_eventsdata
node_teams -->|"reads"| node_teamsdata
node_dekodexhome -->|"uses"| node_problemarena
node_questionpage -->|"calls"| node_dekodexapi
node_dekodexapi -->|"uses"| node_firebaseadmin
node_dekodexapi -->|"uses"| node_firebase
node_dekodexapi -->|"verifies"| node_turnstile
node_dekodexapi -->|"guards"| node_requireauth
node_dekodexapi -->|"reads"| node_dekodexdata
node_leaderboardpage -->|"calls"| node_dekodexapi
node_authpage -->|"uses"| node_authctx
node_authpage -->|"uses"| node_firebase
node_regform -->|"uses"| node_authctx
node_pdsroot -->|"links"| node_pdslab
node_pdsroot -->|"links"| node_pdstheory
node_pdslab -->|"reads"| node_qna

click node_layout "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/layout.jsx"
click node_home "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/page.jsx"
click node_navbar "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/Components/Header/navbar.jsx"
click node_landing "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/Components/Landing/landing.jsx"
click node_footer "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/Components/Footer/footer.jsx"
click node_articles "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/articles/page.jsx"
click node_events "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/events/page.jsx"
click node_teams "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/teams/page.jsx"
click node_techtriad "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/tech-triad/page.jsx"
click node_authpage "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/auth/page.jsx"
click node_regform "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/regform/page.jsx"
click node_regsummary "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/regsummary/page.jsx"
click node_dekodexhome "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/page.jsx"
click node_problemarena "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/ProblemArena.jsx"
click node_questionpage "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/[QuestionID]/page.jsx"
click node_leaderboardpage "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/leaderboard/page.jsx"
click node_pdsroot "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/page.jsx"
click node_pdslab "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/lab/page.jsx"
click node_pdstheory "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/theory/page.jsx"
click node_authctx "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/contexts/authContext.jsx"
click node_firebase "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/backend/firebase.js"
click node_firebaseadmin "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/backend/firebaseAdmin.js"
click node_requireauth "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/backend/requireAuth.js"
click node_dekodexapi "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/api/auth/route.js"
click node_turnstile "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/api/verifyTurnstile/route.js"
click node_articlesdata "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/articles/articles-data.json"
click node_eventsdata "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/events/EventsData.json"
click node_teamsdata "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/teams/content.json"
click node_qna "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/qna/lab-questions.json"
click node_dekodexdata "https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/deKodeX/event-que.json"

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_layout toneBlue
class node_home,node_articles,node_events,node_teams,node_techtriad toneAmber
class node_dekodexhome,node_problemarena,node_questionpage,node_leaderboardpage,node_dekodexapi toneMint
class node_pdsroot,node_pdslab,node_pdstheory toneRose
class node_navbar,node_landing,node_footer,node_authpage,node_regform,node_regsummary,node_authctx,node_firebase,node_firebaseadmin,node_requireauth,node_turnstile toneIndigo
class node_articlesdata,node_eventsdata,node_teamsdata,node_qna,node_dekodexdata toneTeal
```

## Components

### App Shell

Next.js App Router entrypoints and global styling.

- [Root Layout](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/layout.jsx): app shell · Global app wrapper and shared document structure. · `src/app/layout.jsx`

### Public Site

Marketing and content-facing routes.

- [Home](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/page.jsx): landing route · Top-level public landing page. · `src/app/page.jsx`
- [Articles](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/articles/page.jsx): content route · Article browsing and animated article views. · `src/app/articles/page.jsx`
- [Events](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/events/page.jsx): content route · Event listing and showcase page. · `src/app/events/page.jsx`
- [Teams](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/teams/page.jsx): directory route · Team roster and role pages. · `src/app/teams/page.jsx`
- [Tech Triad](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/tech-triad/page.jsx): content route · Standalone informational page. · `src/app/tech-triad/page.jsx`

### deKodeX

Interactive challenge and submission subsystem.

- [deKodeX Home](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/page.jsx): challenge hub · Main challenge arena entry point. · `src/app/dekodeX/page.jsx`
- [Problem Arena](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/ProblemArena.jsx): challenge ui · Interactive question and submission workspace. · `src/app/dekodeX/ProblemArena.jsx`
- [Question Page](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/[QuestionID]/page.jsx): dynamic route · Per-question deKodeX page for a question identifier. · `src/app/dekodeX/[QuestionID]/page.jsx`
- [Leaderboard](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/leaderboard/page.jsx): paginated route · Rankings view for challenge users. · `src/app/leaderboard/page.jsx`
- [deKodeX API](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/api/auth/route.js): api routes · Challenge auth, questions, submissions, leaderboard, and certificates. · `src/app/dekodeX/api/auth/route.js`

### PDS

Practice and lab learning subsystem.

- [PDS Home](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/page.jsx): practice route · Practice-and-lab entry page. · `src/app/pds/page.jsx`
- [PDS Lab](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/lab/page.jsx): lab hub · Topic-driven lab navigation and question flow. · `src/app/pds/lab/page.jsx`
- [PDS Theory](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/pds/theory/page.jsx): theory route · Theory content page for the PDS area. · `src/app/pds/theory/page.jsx`

### Platform

Auth, backend services, and shared UI.

- [Navbar](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/Components/Header/navbar.jsx): shared ui · Primary navigation across the site. · `src/Components/Header/navbar.jsx`
- [Landing](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/Components/Landing/landing.jsx): section ui · Home-page hero and featured sections. · `src/Components/Landing/landing.jsx`
- [Footer](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/Components/Footer/footer.jsx): shared ui · Site-wide footer component. · `src/Components/Footer/footer.jsx`
- [Auth Page](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/auth/page.jsx): auth route · Sign-in and sign-up screen. · `src/app/auth/page.jsx`
- [Registration](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/regform/page.jsx): form route · Application or event registration flow. · `src/app/regform/page.jsx`
- [Summary](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/regsummary/page.jsx): summary route · Post-registration summary and confirmation. · `src/app/regsummary/page.jsx`
- [Auth Context](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/contexts/authContext.jsx): state management · Client-side auth state and token sharing. · `src/contexts/authContext.jsx`
- [Firebase Client](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/backend/firebase.js): client backend · Client-side Firebase access layer. · `src/backend/firebase.js`
- [Firebase Admin](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/backend/firebaseAdmin.js): server backend · Privileged Firebase access for protected operations. · `src/backend/firebaseAdmin.js`
- [Require Auth](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/backend/requireAuth.js): guard · Server-side access control helper. · `src/backend/requireAuth.js`
- [Turnstile Verify](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/app/dekodeX/api/verifyTurnstile/route.js): security api · Bot-check verification for sensitive flows. · `src/app/dekodeX/api/verifyTurnstile/route.js`

### Content Data

Local JSON and static assets consumed by routes.

- [Articles Data](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/articles/articles-data.json): content json · Article metadata and animation descriptors. · `src/data/articles/articles-data.json`
- [Events Data](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/events/EventsData.json): content json · Events catalog and image mappings. · `src/data/events/EventsData.json`
- [Teams Data](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/teams/content.json): content json · Team rosters and membership content. · `src/data/teams/content.json`
- [Question Banks](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/qna/lab-questions.json): json content · PDS and practice question sets. · `src/data/qna/lab-questions.json`
- [Challenge Data](https://github.com/kodeinkgp-technology-web-3-0-society/kik-nextjs/blob/main/src/data/deKodeX/event-que.json): content json · deKodeX question and event data used by routes. · `src/data/deKodeX/event-que.json`

## Connections

- Root Layout → Home: wraps · The root layout surrounds the public entry page.
- Root Layout → Articles: routes · Layout enables all routed pages.
- Root Layout → Events: routes · Layout enables all routed pages.
- Root Layout → Teams: routes · Layout enables all routed pages.
- Root Layout → deKodeX Home: routes · Layout enables all routed pages.
- Root Layout → PDS Home: routes · Layout enables all routed pages.
- Home → Navbar: uses · Home page composes the shared navigation.
- Home → Landing: uses · Home page composes landing sections.
- Home → Footer: uses · Home page includes the shared footer.
- Articles → Articles Data: reads · Article route renders from local article metadata.
- Events → Events Data: reads · Events route renders from local event data.
- Teams → Teams Data: reads · Team pages render from curated roster data.
- deKodeX Home → Problem Arena: uses · Main deKodeX page mounts the interactive arena.
- Question Page → deKodeX API: calls · Dynamic question pages fetch question state and submit results.
- deKodeX API → Firebase Admin: uses · Protected challenge endpoints rely on server Firebase access.
- deKodeX API → Firebase Client: uses · Some challenge flows use client Firebase integration.
- deKodeX API → Turnstile Verify: verifies · Sensitive endpoints verify bot protection tokens.
- deKodeX API → Require Auth: guards · Authenticated challenge operations are protected server-side.
- deKodeX API → Challenge Data: reads · Challenge endpoints resolve questions and titles from local data.
- Leaderboard → deKodeX API: calls · Leaderboard pages fetch paginated ranking data.
- Auth Page → Auth Context: uses · Auth UI shares client login state.
- Auth Page → Firebase Client: uses · Authentication flows connect to Firebase client services.
- Registration → Auth Context: uses · Registration flow shares auth/token state.
- PDS Home → PDS Lab: links · PDS home routes into the lab experience.
- PDS Home → PDS Theory: links · PDS home routes into theory content.
- PDS Lab → Question Banks: reads · Lab questions are driven by local question banks.