# mjcet-acm/main-codebase architecture

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

- Interactive diagram: https://gitdiagram.com/mjcet-acm/main-codebase
- Repository: https://github.com/mjcet-acm/main-codebase

## Overview

1. **Monorepo orchestration layer**
   - This repo is an Nx + pnpm monorepo. Nx is the task runner/build orchestrator across apps and shared packages, while pnpm manages workspace dependencies.
   - The root also contains GitHub Actions workflows that deploy individual apps independently.

2. **Three primary application boundaries**
   - `apps/web`: the public ACM MJCET website.
   - `apps/admin`: an internal admin portal.
   - `apps/cf-server`: a Cloudflare Worker backend API.
   - These are separate deployable units with their own configs, build settings, and runtime targets.

3. **Public website frontend (`apps/web`)**
   - Built with Next.js App Router and deployed to Cloudflare Workers via OpenNext.
   - It is mostly a content/marketing site with pages such as home, about, blogs, events, team, contact, join, profile, and a test page.
   - The site uses a component-heavy UI structure, including reusable sections, animation components, blog presentation components, and Tailwind-based styling.

4. **Content and presentation data in the web app**
   - The web app relies on local public assets and JSON files like `execom.json` and `team.json`.
   - That indicates a hybrid content model: some content is bundled into the frontend as static data, while page shells and interactions are rendered by Next.js.

5. **Admin portal (`apps/admin`)**
   - Also a Next.js app deployed to Cloudflare Workers.
   - It includes authentication flow handling (`app/auth/callback`) and user/settings-related UI components.
   - The presence of a Supabase client and `useUser` hook suggests the admin boundary is identity-driven and likely depends on Supabase for session/user state.

6. **Backend API worker (`apps/cf-server`)**
   - This is the main server-side API layer, implemented as a Cloudflare Worker using Hono-style routing/controller structure.
   - Routes are split by domain: `blog` and `user.auth`.
   - Controllers separate concerns further into blog CRUD and profile/auth logic, which is a clean API boundary for the frontend apps to consume.

7. **Persistence layer**
   - The backend uses Cloudflare D1 as its database, with Drizzle ORM/schema files under `apps/cf-server/src/db`.
   - The database domain appears to cover profiles and blogs, with migrations checked into `drizzle/`.
   - This means API state is stored at the edge rather than in an external traditional server.

8. **Backend request flow**
   - Requests enter `apps/cf-server` through route modules.
   - Routes dispatch into controllers, which perform validation and database access.
   - There is a shared email validation helper, indicating some request-level validation before persistence or auth actions.

9. **Shared libraries**
   - `packages/api-endpoints` centralizes endpoint definitions or constants, likely used to avoid hardcoding API URLs across apps.
   - `packages/portfolio-components` contains reusable UI/portfolio primitives, especially hero and achievement components, for consumption by apps that need consistent design blocks.
   - These packages reduce duplication and form the shared layer of the architecture.

10. **Deployment model**
   - All three apps are configured for Cloudflare Workers deployment, with separate Wrangler/OpenNext configs.
   - GitHub Actions workflows exist for deploying the admin app, web app, and backend worker independently.
   - The deployment unit is therefore per app, not per monorepo.

11. **Runtime and technology boundaries**
   - Frontends: Next.js + React + Tailwind CSS + TypeScript.
   - Backend: Cloudflare Workers + Hono + D1 + Drizzle.
   - Authentication and identity: Supabase is used on the admin side, while backend auth/profile routes suggest a separate app-facing auth flow.

12. **Architecture summary for a diagram**
   - Draw the repo as a monorepo root with three deployable apps and two shared packages.
   - Show `web` and `admin` as independent Next.js edge apps.
   - Show `cf-server` as the API worker with routes/controllers feeding D1 through Drizzle.
   - Show shared packages feeding the apps for endpoint constants and reusable UI components.

Main entry points: [`apps/web`](https://github.com/mjcet-acm/main-codebase/tree/main/apps/web) (Web app), [`apps/admin`](https://github.com/mjcet-acm/main-codebase/tree/main/apps/admin) (Admin app), [`apps/cf-server`](https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server) (API worker), [`nx.json`](https://github.com/mjcet-acm/main-codebase/blob/main/nx.json) (Nx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_root["Monorepo"]
  node_nx{{"Nx<br/>orchestrator<br/>[nx.json]"}}
  node_pnpm{{"pnpm<br/>workspace manager"}}
end

subgraph group_apps["Deployable apps"]
  node_web["Web app<br/>Next.js site"]
  node_admin["Admin app<br/>Next.js portal"]
  node_cfserver["API worker<br/>Cloudflare Worker API"]
  node_web_pages["Web pages<br/>App Router pages"]
  node_web_ui["Web UI<br/>components"]
  node_web_content["Static content<br/>json/assets"]
  node_admin_auth["Admin auth<br/>auth flow<br/>[page.tsx]"]
  node_admin_ui["Admin UI<br/>components"]
  node_routes["API routes<br/>route modules"]
  node_controllers["Controllers<br/>business logic"]
  node_db[("D1 schema<br/>Drizzle DB layer")]
  node_validation["Validation<br/>helper<br/>[validate-email.ts]"]
end

subgraph group_shared["Shared packages"]
  node_api_endpoints["API endpoints<br/>shared lib<br/>[api-endpoints.ts]"]
  node_portfolio_components["Portfolio UI<br/>shared lib"]
end

subgraph group_infra["CI / deploy"]
  node_deploy_web["Deploy web<br/>GitHub Action"]
  node_deploy_admin["Deploy admin<br/>GitHub Action"]
  node_deploy_api["Deploy API<br/>GitHub Action"]
end

node_nx -->|"orchestrates"| node_web
node_nx -->|"orchestrates"| node_admin
node_nx -->|"orchestrates"| node_cfserver
node_pnpm -->|"links deps"| node_web
node_pnpm -->|"links deps"| node_admin
node_pnpm -->|"links deps"| node_cfserver
node_web -->|"renders"| node_web_pages
node_web -->|"composes"| node_web_ui
node_web -->|"loads content"| node_web_content
node_web -->|"uses"| node_portfolio_components
node_admin -->|"handles"| node_admin_auth
node_admin -->|"composes"| node_admin_ui
node_admin -->|"calls"| node_api_endpoints
node_admin -->|"consumes API"| node_cfserver
node_cfserver -->|"exposes"| node_routes
node_routes -->|"dispatches to"| node_controllers
node_controllers -->|"persists via"| node_db
node_controllers -->|"validates"| node_validation
node_db -.->|"shares contracts"| node_api_endpoints
node_deploy_web -->|"deploys"| node_web
node_deploy_admin -->|"deploys"| node_admin
node_deploy_api -->|"deploys"| node_cfserver

click node_nx "https://github.com/mjcet-acm/main-codebase/blob/main/nx.json"
click node_pnpm "https://github.com/mjcet-acm/main-codebase/blob/main/pnpm-workspace.yaml"
click node_web "https://github.com/mjcet-acm/main-codebase/tree/main/apps/web"
click node_admin "https://github.com/mjcet-acm/main-codebase/tree/main/apps/admin"
click node_cfserver "https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server"
click node_web_pages "https://github.com/mjcet-acm/main-codebase/tree/main/apps/web/app"
click node_web_ui "https://github.com/mjcet-acm/main-codebase/tree/main/apps/web/components"
click node_web_content "https://github.com/mjcet-acm/main-codebase/tree/main/apps/web/public"
click node_admin_auth "https://github.com/mjcet-acm/main-codebase/blob/main/apps/admin/app/auth/callback/page.tsx"
click node_admin_ui "https://github.com/mjcet-acm/main-codebase/tree/main/apps/admin/components"
click node_routes "https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server/src/routes"
click node_controllers "https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server/src/controllers"
click node_db "https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server/src/db"
click node_validation "https://github.com/mjcet-acm/main-codebase/blob/main/apps/cf-server/src/helpers/validate-email.ts"
click node_api_endpoints "https://github.com/mjcet-acm/main-codebase/blob/main/packages/api-endpoints/src/lib/api-endpoints.ts"
click node_portfolio_components "https://github.com/mjcet-acm/main-codebase/blob/main/packages/portfolio-components/src/lib/portfolio-components.tsx"
click node_deploy_web "https://github.com/mjcet-acm/main-codebase/blob/main/.github/workflows/deploy-web-to-workers.yml"
click node_deploy_admin "https://github.com/mjcet-acm/main-codebase/blob/main/.github/workflows/deploy-admin-to-workers.yml"
click node_deploy_api "https://github.com/mjcet-acm/main-codebase/blob/main/.github/workflows/deploy-cf-backend-worker.yml"

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_nx,node_pnpm toneBlue
class node_web,node_admin,node_cfserver,node_web_pages,node_web_ui,node_web_content,node_admin_auth,node_admin_ui,node_routes,node_controllers,node_db,node_validation toneAmber
class node_api_endpoints,node_portfolio_components toneMint
class node_deploy_web,node_deploy_admin,node_deploy_api toneRose
```

## Components

### Monorepo

Nx + pnpm workspace orchestration and repo-wide config.

- [Nx](https://github.com/mjcet-acm/main-codebase/blob/main/nx.json): orchestrator · Task runner and build coordination for the workspace. · `nx.json`
- [pnpm](https://github.com/mjcet-acm/main-codebase/blob/main/pnpm-workspace.yaml): workspace manager · Manages monorepo dependencies and workspace linking. · `pnpm-workspace.yaml`

### Deployable apps

Three independently deployed application boundaries.

- [Web app](https://github.com/mjcet-acm/main-codebase/tree/main/apps/web): Next.js site · Public ACM MJCET website deployed to Cloudflare Workers. · `apps/web`
- [Admin app](https://github.com/mjcet-acm/main-codebase/tree/main/apps/admin): Next.js portal · Internal admin portal with auth and settings flows. · `apps/admin`
- [API worker](https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server): Cloudflare Worker API · Backend API with route/controller structure and D1 persistence. · `apps/cf-server`
- [Web pages](https://github.com/mjcet-acm/main-codebase/tree/main/apps/web/app): App Router pages · Content pages for marketing, blogs, events, team, and profile. · `apps/web/app`
- [Web UI](https://github.com/mjcet-acm/main-codebase/tree/main/apps/web/components): components · Reusable sections, animations, blog UI, and shared presentation pieces. · `apps/web/components`
- [Static content](https://github.com/mjcet-acm/main-codebase/tree/main/apps/web/public): json/assets · Bundled JSON data and public assets used by the site. · `apps/web/public`
- [Admin auth](https://github.com/mjcet-acm/main-codebase/blob/main/apps/admin/app/auth/callback/page.tsx): auth flow · Callback page and user/session handling for the portal. · `apps/admin/app/auth/callback/page.tsx`
- [Admin UI](https://github.com/mjcet-acm/main-codebase/tree/main/apps/admin/components): components · Auth and settings UI plus user-state hooks and Supabase client. · `apps/admin/components`
- [API routes](https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server/src/routes): route modules · Domain routing for blog and user/auth endpoints. · `apps/cf-server/src/routes`
- [Controllers](https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server/src/controllers): business logic · Blog CRUD and profile/auth handlers behind the API routes. · `apps/cf-server/src/controllers`
- [D1 schema](https://github.com/mjcet-acm/main-codebase/tree/main/apps/cf-server/src/db): Drizzle DB layer · Database schema, Drizzle access, and migration state for profiles and blogs. · `apps/cf-server/src/db`
- [Validation](https://github.com/mjcet-acm/main-codebase/blob/main/apps/cf-server/src/helpers/validate-email.ts): helper · Request-level email validation used by the API worker. · `apps/cf-server/src/helpers/validate-email.ts`

### Shared packages

Reusable libraries consumed across apps.

- [API endpoints](https://github.com/mjcet-acm/main-codebase/blob/main/packages/api-endpoints/src/lib/api-endpoints.ts): shared lib · Central endpoint definitions and constants for app-to-API calls. · `packages/api-endpoints/src/lib/api-endpoints.ts`
- [Portfolio UI](https://github.com/mjcet-acm/main-codebase/blob/main/packages/portfolio-components/src/lib/portfolio-components.tsx): shared lib · Reusable hero and achievement components shared across portfolio surfaces. · `packages/portfolio-components/src/lib/portfolio-components.tsx`

### CI / deploy

Repository automation and deployment workflows.

- [Deploy web](https://github.com/mjcet-acm/main-codebase/blob/main/.github/workflows/deploy-web-to-workers.yml): GitHub Action · Workflow for independently deploying the public site. · `.github/workflows/deploy-web-to-workers.yml`
- [Deploy admin](https://github.com/mjcet-acm/main-codebase/blob/main/.github/workflows/deploy-admin-to-workers.yml): GitHub Action · Workflow for independently deploying the admin portal. · `.github/workflows/deploy-admin-to-workers.yml`
- [Deploy API](https://github.com/mjcet-acm/main-codebase/blob/main/.github/workflows/deploy-cf-backend-worker.yml): GitHub Action · Workflow for independently deploying the backend worker. · `.github/workflows/deploy-cf-backend-worker.yml`

## Connections

- Nx → Web app: orchestrates · Nx coordinates builds and tasks for the web app.
- Nx → Admin app: orchestrates · Nx coordinates builds and tasks for the admin app.
- Nx → API worker: orchestrates · Nx coordinates builds and tasks for the API worker.
- pnpm → Web app: links deps · pnpm links workspace dependencies into the web app.
- pnpm → Admin app: links deps · pnpm links workspace dependencies into the admin app.
- pnpm → API worker: links deps · pnpm links workspace dependencies into the API worker.
- Web app → Web pages: renders · The web app serves its App Router page tree.
- Web app → Web UI: composes · The web app composes reusable UI and section components.
- Web app → Static content: loads content · The web app reads bundled JSON data and public assets.
- Web app → Portfolio UI: uses · The web app reuses shared portfolio presentation components.
- Admin app → Admin auth: handles · The admin app manages authentication callback flow.
- Admin app → Admin UI: composes · The admin app uses auth/settings components and hooks.
- Admin app → API endpoints: calls · The admin app uses shared endpoint definitions for backend access.
- Admin app → API worker: consumes API · The admin portal talks to the backend worker for identity and data.
- API worker → API routes: exposes · The worker exposes domain routes for blog and auth/user APIs.
- API routes → Controllers: dispatches to · Routes delegate requests to domain controllers.
- Controllers → D1 schema: persists via · Controllers read and write through the D1/Drizzle data layer.
- Controllers → Validation: validates · API handlers validate inputs before persistence or auth actions.
- D1 schema → API endpoints: shares contracts · Shared endpoint/data contracts help align frontend and backend boundaries.
- Deploy web → Web app: deploys · Workflow deploys the public website independently.
- Deploy admin → Admin app: deploys · Workflow deploys the admin portal independently.
- Deploy API → API worker: deploys · Workflow deploys the backend worker independently.
