Skip to content

kanakkholwal/college-ecosystem

BranchesTags

Repository files navigation

College Ecosystem

An open-source, full-stack college management platform — built as a monorepo with Next.js, Express, Go, and Docker.

License: MPL 2.0 Node.js Bun Next.js TypeScript Go Docker MongoDB PostgreSQL Redis PRs Welcome

Screenshot

Ask DeepWiki

Table of Contents

Overview

College Ecosystem is a production-grade, monorepo-based college management and student engagement platform. It consolidates academic tools, campus resources, community interaction, and administrative dashboards into a single, cohesive system.

The project powers app.nith.eu.org (Platform) and nith.eu.org (Website) with a multi-service backend spanning Node.js, Go, and a dedicated mail microservice — all orchestrated via Turborepo and Docker Compose.

Monorepo Apps

The repository is organized into five independent applications under the apps/ directory:

App Description Tech Port
Platform Primary student and admin-facing application. Handles academic results, schedules, community features, AI chatbot, attendance tracking, hostel management, and role-based dashboards. Next.js 16, React 19, Tailwind CSS 4, Drizzle ORM, Mongoose, Better Auth, Vercel AI SDK 3000
Website Public-facing college website with landing pages, announcements, and informational content. Next.js 15, React 19, Tailwind CSS 4, Framer Motion, AOS 3002
Server REST API and WebSocket server for data-intensive operations — result scraping, Excel processing, real-time updates, and background jobs. Express 4, TypeScript, Mongoose, Socket.IO, Redis, Multer 8080
Go Server High-performance microservice for compute-heavy tasks like web scraping and result parsing. Go 1.24, Fiber v2, GoQuery 8080
Mail Server Transactional email microservice with templated emails (welcome, password reset, result notifications). Deployable to Cloudflare Workers via OpenNext. Next.js, React Email, Nodemailer, Wrangler 3001

Architecture

graph TB
    subgraph Client["Client Layer"]
        Browser["Browser / PWA"]
    end

    subgraph Frontend["Frontend Apps"]
        Platform["Platform<br/>(Next.js 16)"]
        Website["Website<br/>(Next.js 15)"]
    end

    subgraph Backend["Backend Services"]
        Server["Node Server<br/>(Express + Socket.IO)"]
        GoServer["Go Server<br/>(Fiber v2)"]
        MailServer["Mail Server<br/>(React Email + Nodemailer)"]
    end

    subgraph Data["Data Layer"]
        MongoDB[(MongoDB)]
        Postgres[(PostgreSQL)]
        Redis[(Redis)]
        Supabase[(Supabase)]
    end

    subgraph Infra["Infrastructure"]
        Docker["Docker Compose"]
        Turbo["Turborepo"]
        GHA["GitHub Actions"]
    end

    Browser --> Platform
    Browser --> Website
    Platform --> Server
    Platform --> GoServer
    Platform --> MailServer
    Platform --> MongoDB
    Platform --> Postgres
    Platform --> Redis
    Platform --> Supabase
    Server --> MongoDB
    Server --> Redis
    GoServer --> Browser

    Docker -.-> Platform
    Docker -.-> Website
    Docker -.-> Server
    Docker -.-> MailServer
    Docker -.-> MongoDB
    Docker -.-> Postgres
    Docker -.-> Redis
    Turbo -.-> Platform
    Turbo -.-> Website
    Turbo -.-> Server
    Turbo -.-> MailServer
    GHA -.-> Docker
    GHA -.-> Turbo
Loading

Project Structure

college-ecosystem/
├── apps/
│   ├── platform/          # Main college platform (Next.js 16)
│   │   ├── app/           # App Router (pages, layouts, API routes)
│   │   ├── src/           # Shared source (hooks, lib, utils)
│   │   ├── @/             # Path alias modules
│   │   ├── migrations/    # Drizzle ORM migrations
│   │   └── Dockerfile
│   ├── website/           # Public college website (Next.js 15)
│   │   ├── app/           # App Router
│   │   ├── @/             # Shared components
│   │   └── Dockerfile
│   ├── server/            # REST API + WebSocket server (Express)
│   │   ├── src/
│   │   │   ├── controllers/
│   │   │   ├── models/
│   │   │   ├── routes/
│   │   │   ├── services/
│   │   │   └── scripts/
│   │   └── Dockerfile
│   ├── go-server/         # High-perf microservice (Go + Fiber)
│   │   ├── cmd/
│   │   ├── routes/
│   │   ├── middleware/
│   │   ├── pkg/
│   │   └── Dockerfile
│   └── mail-server/       # Email microservice (React Email)
│       ├── emails/        # Email templates
│       ├── app/           # API routes
│       └── Dockerfile
├── content/               # Chatbot reference data
├── local-setup/           # Local development helpers
├── docker-compose.yml     # Full-stack orchestration
├── turbo.json             # Turborepo task config
├── package.json           # Root workspace config
├── .env.example           # Environment variable template
├── CONTRIBUTING.md        # Contribution guidelines
├── deployment.md          # GCP Cloud Run deployment guide
└── LICENSE                # Mozilla Public License 2.0

Tech Stack

Frontend

Technology Usage
Next.js 15 / 16 React framework with App Router, SSR, ISR, and API routes
React 19 UI library with Server Components and concurrent features
TypeScript 5.x Type-safe development across all apps
Tailwind CSS 4 Utility-first styling with PostCSS
Radix UI Accessible, unstyled component primitives (Shadcn UI)
Framer Motion Declarative animations and gestures
Recharts Data visualization and charting
Lucide React Icon library
Zustand Lightweight client state management
TanStack Query Server state management and caching
TanStack Table Headless table UI
React Hook Form + Zod Form handling and schema validation
nuqs Type-safe URL search params state
Serwist PWA service worker tooling

Backend

Technology Usage
Express 4 Node.js REST API framework
Socket.IO Real-time bidirectional communication
Go 1.24 High-performance backend microservice
Fiber v2 Express-inspired Go web framework
GoQuery HTML parsing and web scraping (Go)
Multer File upload handling
Nodemailer Email delivery via SMTP
React Email Build email templates with React components
Vercel AI SDK LLM integration (Google Gemini, Mistral, DeepSeek)
Better Auth Authentication and session management

Database & Caching

Technology Usage
MongoDB + Mongoose Primary document database for unstructured data
PostgreSQL + Drizzle ORM Relational database with type-safe ORM and migrations
Redis + ioredis In-memory caching and rate limiting
Supabase Managed Postgres with real-time subscriptions
Neon Serverless Postgres (via @neondatabase/serverless)

DevOps & Tooling

Technology Usage
Turborepo Monorepo build system with caching and task orchestration
Bun 1.3 JavaScript runtime and package manager
Docker + Compose Containerized development and production environments
GitHub Actions CI/CD pipelines for automated deployments
Vercel Hosting for Platform and Server apps
Cloudflare Workers Edge deployment for Mail Server (via OpenNext)
Google Cloud Run Container hosting for server microservices
ESLint 9 Code linting
Prettier Code formatting
Drizzle Kit Database migration tooling

Features

Academic Management

  • Results Portal — Search and view semester results with batch, branch, and programme filtering; aggregate rankings across college, batch, and section
  • Syllabus Browser — Browse and search course syllabi by department, type, and semester
  • Academic Calendar — View events, important dates, and semester schedules in calendar and list views
  • Class Schedules & Timetables — Access and manage class timetables per section and department
  • Classroom Availability — Check real-time room availability in lecture halls for booking

Community & Communication

  • Community Posts — Reddit-style discussion board with upvotes, comments, and topic threads
  • Whisper Room — Anonymous messaging feature for students
  • Polls & Voting — Create and participate in campus-wide polls
  • Announcements — College-wide announcements broadcast to all users
  • AI Chatbot — College-specific question-answering assistant powered by Google Gemini and Mistral LLMs

Student Tools

  • Attendance Tracker — Personal attendance logging and summary views
  • Out Pass System — Digital out-pass applications and approvals for hostellers
  • Hostel Room Allotment — Room allocation management for students
  • Career & Benefits — Career resources and student benefit information
  • User Profiles — Public student profiles with academic information

Administrative Dashboards

  • Admin Dashboard — User management, result imports, bulk operations, and system settings
  • Faculty Dashboard — Faculty-specific tools and class management
  • CR Dashboard — Class representative tools for attendance and schedules
  • Warden & Chief Warden Dashboards — Hostel management, out-pass approvals, and room allotment
  • Guard Dashboard — Gate pass verification tools
  • Role-Based Access Control — Granular permissions for Admin, Faculty, Student, CR, HOD, Warden, Chief Warden, and Guard roles

Technical Capabilities

  • Progressive Web App (PWA) — Installable on mobile and desktop with offline capabilities via Serwist service worker
  • Real-time Updates — Live data sync via Socket.IO WebSockets
  • Multi-Database Architecture — MongoDB for documents, PostgreSQL for relational data, Redis for caching
  • AI-Powered Features — LLM-based chatbot and content generation via Vercel AI SDK
  • Email Notifications — Templated transactional emails (welcome, password reset, result updates)
  • Excel Import/Export — Bulk data operations via ExcelJS and read-excel-file
  • Sitemap & SEO — Dynamic sitemap generation and OpenGraph image support
  • Dark Mode — System-aware theme switching via next-themes

Getting Started

Prerequisites

  • Node.js >= 20
  • Bun >= 1.3 (package manager)
  • Docker and Docker Compose (for local infrastructure)
  • Go >= 1.24 (for the Go server)

Quick Start with Docker

# Clone the repository
git clone https://github.com/kanakkholwal/college-ecosystem.git
cd college-ecosystem

# Copy environment template and configure
cp .env.example .env

# Start all services
docker compose up --build

This starts the full stack:

Service URL
Platform http://localhost:3000
Mail Server http://localhost:3001
Website http://localhost:3002
Server http://localhost:8080

Local Development (without Docker)

# Install all workspace dependencies
bun install

# Run all apps concurrently
bun run dev

# Or run individual apps
bun run dev:platform    # Platform on :3000
bun run dev:server      # Server on :8080
bun run dev:mail        # Mail Server on :3001
bun run dev:website     # Website on :3002

Database Setup

# Push Drizzle schema to PostgreSQL
cd apps/platform
bun run db:push

# Generate migrations
bun run db:generate

# Apply migrations
bun run db:migrate

CI/CD & GitHub Workflows

The project uses GitHub Actions for continuous deployment with path-based triggers — only deploying services that have changed.

Workflow Trigger Target File
Deploy Platform Push to main in apps/platform/** Vercel (Production) cd-platform-vercel.yml
Deploy Server Push to main in apps/server/** Vercel (Production) cd-server-vercel.yml

Both workflows:

  1. Check out code and set up Bun
  2. Install dependencies
  3. Run linting and tests
  4. Build and deploy to Vercel (production on main, preview on PRs)

See deployment.md for Google Cloud Run deployment instructions (Docker-based).

Deployment

The project supports multiple deployment targets:

App Production Host Method
Platform Vercel GitHub Actions → Vercel CLI
Website Vercel GitHub Actions → Vercel CLI
Server Vercel / GCP Cloud Run GitHub Actions → Vercel CLI / Docker
Go Server GCP Cloud Run Docker container
Mail Server Cloudflare Workers OpenNext + Wrangler

For self-hosting with Docker Compose, see the Quick Start section. For GCP Cloud Run, see deployment.md.

Contributing

We welcome contributions of all kinds — code, design, documentation, and bug reports.

Please read our CONTRIBUTING.md for:

  • Development setup instructions
  • Coding guidelines and commit conventions
  • How to submit pull requests
  • Design contribution opportunities

License

This project is licensed under the Mozilla Public License 2.0.

About

Monorepo for college ecosystem project

app.nith.eu.org

Topics

typescript mongoose nextjs postgresql gcp monorepo google-cloud-platform tailwindcss github-actions

Resources

Readme

License

MPL-2.0 license

Contributing

Contributing
Activity

Stars

19 stars

Watchers

1 watching

Forks

6 forks
Report repository

Contributors

Languages