ITADN
kanakkholwal/college-ecosystem
代码 动态 Issues7 合并请求56 版本
kanakkholwal/college-ecosystem · 文件 下载 ZIP
文件最后提交记录最后更新时间
README.md
以下内容由 AI 翻译，如有问题请点此提交 issue 反馈

学院生态系统

一个开源的全栈学院管理平台 —— 基于 Next.js、Express、Go 和 Docker 构建的 monorepo。

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

Screenshot

Ask DeepWiki

目录

概述

College Ecosystem 是一个生产级、基于 monorepo 的学院管理与学生互动平台。它将学术工具、校园资源、社区互动和管理仪表盘整合到一个统一的系统中。

该项目为 app.nith.eu.org（平台）和 nith.eu.org（网站）提供支持，其多服务后端涵盖 Node.js、Go 以及一个专用的邮件微服务——所有服务均通过 Turborepo 和 Docker Compose 进行编排。

Monorepo 应用

该仓库在 apps/ 目录下组织为五个独立的应用：

应用描述技术端口
Platform面向学生和管理员的主要应用。处理学业成绩、日程安排、社区功能、AI 聊天机器人、考勤跟踪、宿舍管理以及基于角色的仪表盘。Next.js 16, React 19, Tailwind CSS 4, Drizzle ORM, Mongoose, Better Auth, Vercel AI SDK3000
Website面向公众的学院网站，包含落地页、公告和信息内容。Next.js 15, React 19, Tailwind CSS 4, Framer Motion, AOS3002
Server用于数据密集型操作的 REST API 和 WebSocket 服务器——成绩抓取、Excel 处理、实时更新和后台任务。Express 4, TypeScript, Mongoose, Socket.IO, Redis, Multer8080
Go Server用于网络抓取和成绩解析等计算密集型任务的高性能微服务。Go 1.24, Fiber v2, GoQuery8080
Mail Server带有模板化邮件（欢迎邮件、密码重置、成绩通知）的事务性邮件微服务。可通过 OpenNext 部署到 Cloudflare Workers。Next.js, React Email, Nodemailer, Wrangler3001

架构

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

项目结构

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

Star 历史

Star History Chart

技术栈

前端

TechnologyUsage
Next.js 15 / 16React framework with App Router, SSR, ISR, and API routes
React 19UI library with Server Components and concurrent features
TypeScript 5.xType-safe development across all apps
Tailwind CSS 4Utility-first styling with PostCSS
Radix UIAccessible, unstyled component primitives (Shadcn UI)
Framer MotionDeclarative animations and gestures
RechartsData visualization and charting
Lucide ReactIcon library
ZustandLightweight client state management
TanStack QueryServer state management and caching
TanStack TableHeadless table UI
React Hook Form + ZodForm handling and schema validation
nuqsType-safe URL search params state
SerwistPWA service worker tooling

后端

TechnologyUsage
Express 4Node.js REST API framework
Socket.IOReal-time bidirectional communication
Go 1.24High-performance backend microservice
Fiber v2Express-inspired Go web framework
GoQueryHTML parsing and web scraping (Go)
MulterFile upload handling
NodemailerEmail delivery via SMTP
React EmailBuild email templates with React components
Vercel AI SDKLLM integration (Google Gemini, Mistral, DeepSeek)
Better AuthAuthentication and session management

数据库与缓存

技术用途
MongoDB + Mongoose用于非结构化数据的主要文档数据库
PostgreSQL + Drizzle ORM具有类型安全 ORM 和迁移功能的关系型数据库
Redis + ioredis内存缓存和速率限制
Supabase支持实时订阅的托管 Postgres
Neon无服务器 Postgres（通过 @neondatabase/serverless）

DevOps 与工具

TechnologyUsage
TurborepoMonorepo build system with caching and task orchestration
Bun 1.3JavaScript runtime and package manager
Docker + ComposeContainerized development and production environments
GitHub ActionsCI/CD pipelines for automated deployments
VercelHosting for Platform and Server apps
Cloudflare WorkersEdge deployment for Mail Server (via OpenNext)
Google Cloud RunContainer hosting for server microservices
ESLint 9Code linting
PrettierCode formatting
Drizzle KitDatabase migration tooling

功能

学术管理

  • 成绩门户 — 按批次、专业和课程筛选，搜索并查看学期成绩；汇总学院、批次和班级的排名
  • 教学大纲浏览器 — 按系别、类型和学期浏览和搜索课程教学大纲
  • 学术日历 — 以日历和列表视图查看活动、重要日期和学期日程
  • 课程表与时刻表 — 按班级和系别访问和管理课程时刻表
  • 教室可用性 — 查看讲堂的实时房间可用性以进行预订

社区与沟通

  • 社区帖子 — 类似 Reddit 的讨论板，支持点赞、评论和主题线程
  • 耳语室 — 供学生使用的匿名消息功能
  • 投票与表决 — 创建并参与全校范围的投票
  • 公告 — 向所有用户广播的学院级公告
  • AI 聊天机器人 — 由 Google Gemini 和 Mistral LLM 驱动的学院专属问答助手

学生工具

  • 出勤追踪器 — 个人出勤记录和汇总视图
  • 外出通行证系统 — 住宿生的数字外出通行证申请和审批
  • 宿舍房间分配 — 学生房间分配管理
  • 职业与福利 — 职业资源和学生福利信息
  • 用户资料 — 包含学术信息的公开学生资料

管理仪表板

  • Admin Dashboard — 用户管理、成绩导入、批量操作和系统设置
  • Faculty Dashboard — 教师专用工具和班级管理
  • CR Dashboard — 班级代表用于考勤和日程的工具
  • Warden & Chief Warden Dashboards — 宿舍管理、外出通行证审批和房间分配
  • Guard Dashboard — 门禁通行证验证工具
  • Role-Based Access Control — 针对 Admin、Faculty、Student、CR、HOD、Warden、Chief Warden 和 Guard 角色的细粒度权限

Technical Capabilities

  • Progressive Web App (PWA) — 可通过 Serwist service worker 在移动设备和桌面端安装，并具备离线功能
  • Real-time Updates — 通过 Socket.IO WebSockets 进行实时数据同步
  • Multi-Database Architecture — 使用 MongoDB 存储文档，PostgreSQL 存储关系型数据，Redis 用于缓存
  • AI-Powered Features — 通过 Vercel AI SDK 实现基于 LLM 的聊天机器人和内容生成
  • Email Notifications — 模板化事务性电子邮件（欢迎、密码重置、成绩更新）
  • Excel Import/Export — 通过 ExcelJS 和 read-excel-file 进行批量数据操作
  • Sitemap & SEO — 动态站点地图生成和 OpenGraph 图像支持
  • Dark Mode — 通过 next-themes 实现系统感知的主题切换

快速入门

前置条件

  • Node.js >= 20
  • Bun >= 1.3 (包管理器)
  • Docker 和 Docker Compose (用于本地基础设施)
  • Go >= 1.24 (用于 Go 服务器)

使用 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

这将启动完整的技术栈：

服务URL
Platformhttp://localhost:3000
Mail Serverhttp://localhost:3001
Websitehttp://localhost:3002
Serverhttp://localhost:8080

本地开发（不使用 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

数据库设置

# 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

该项目使用 GitHub Actions 进行持续部署，并基于路径触发——仅部署已更改的服务。

工作流触发条件目标文件
Deploy Platform在 apps/platform/** 中推送至 mainVercel (Production)cd-platform-vercel.yml
Deploy Server在 apps/server/** 中推送至 mainVercel (Production)cd-server-vercel.yml

两个工作流均：

  1. 检出代码并设置 Bun
  2. 安装依赖项
  3. 运行 Lint 和测试
  4. 构建并部署到 Vercel（main 上为生产环境，PR 上为预览环境）

请参阅 deployment.md 获取 Google Cloud Run 部署说明（基于 Docker）。

部署

该项目支持多种部署目标：

应用生产环境主机方法
PlatformVercelGitHub Actions → Vercel CLI
WebsiteVercelGitHub Actions → Vercel CLI
ServerVercel / GCP Cloud RunGitHub Actions → Vercel CLI / Docker
Go ServerGCP Cloud RunDocker 容器
Mail ServerCloudflare WorkersOpenNext + Wrangler

如需使用 Docker Compose 进行自托管，请参阅 快速入门 部分。关于 GCP Cloud Run，请参阅 deployment.md。

贡献

我们欢迎各种形式的贡献——代码、设计、文档以及错误报告。

请阅读我们的 CONTRIBUTING.md，了解：

  • 开发环境搭建说明
  • 编码规范与提交约定
  • 如何提交拉取请求
  • 设计贡献机会

许可证

本项目采用 Mozilla Public License 2.0 授权。