EduCMS

EduCMS is a cloud-based educational Content Management System for institutions that need a public content site and a secure role-based admin panel. It manages posts, categories, tags, comments, media, users, SEO metadata, analytics, and editorial workflows.

Project framing for submission:

EduCMS - A Cloud-Based Educational Content Management System for Institutional Publishing and Learning Resource Governance

Contents

• Live Demo
• Project Status
• How to Review This Project
• Master's Submission
• Features
• Tech Stack
• Repository Structure
• Documentation
• Local Setup
• Running the App
• Testing
• API Documentation
• Architecture Summary
• Deployment
• Known Limitations

Live Demo

Resource	Link
Public site	https://educms-sandy.vercel.app
Admin panel	https://educms-sandy.vercel.app/admin
API	https://educms-api.onrender.com
API docs	https://educms-api.onrender.com/api/docs
OpenAPI JSON	https://educms-api.onrender.com/api/openapi.json
Repository	https://github.com/Ericokim/educms

Demo accounts all use password Password123!.

Email	Role
admin@educms.local	Admin
editor@educms.local	Editor
author@educms.local	Author
subscriber@educms.local	Subscriber

Project Status

Area	Status
Application	Implemented: public site, admin panel, REST API, PostgreSQL schema, RBAC, comments, media, analytics, and API docs.
Deployment	Deployed: frontend on Vercel, API and PostgreSQL on Render.
Tests	Verified locally: 89 API integration tests + 22 web component tests = 111 automated workspace tests.
Documentation	Complete: project docs and Master's submission documents are linked from this README.
Manual checks	Still needed before recording: wake Render API, recheck /api/health with GET, and run a browser login/admin smoke test.

How to Review This Project

For a quick evaluation path:

1. Open the public site.
2. Open the admin panel and sign in with the admin demo account.
3. Open the API docs to wake the Render API and inspect/test endpoints.
4. Read the Final Report for the full academic write-up.
5. Review System Architecture, Cloud Deployment, QA Report, and Security Review for technical evidence.
6. Check Manual Demo Checklist before recording or grading a live walkthrough.

Master's Submission

Use this section as the main examiner-facing table of contents.

Area	Document	Purpose
Research	docs/masters/research-review.md	Problem context and short literature/research review.
Checkpoint mapping	docs/masters/checkpoint-mapping.md	Requirement-by-requirement mapping for the checkpoint.
Architecture	docs/masters/system-architecture.md	Formal architecture explanation and diagrams.
Database design	docs/masters/database-design.md	PostgreSQL design and justification.
Cloud deployment	docs/masters/cloud-deployment.md	Vercel, Render, PostgreSQL, live links, env vars, and limitations.
QA	docs/masters/qa-report.md	Test evidence and verification notes.
Security	docs/masters/security-review.md	Auth, RBAC, validation, uploads, risks, and manual checks.
Final report	docs/masters/final-report.md	Main 2,500-3,500 word report.
Reflection	docs/masters/reflection-report.md	Short reflection on the project and submission work.
Presentation	docs/masters/presentation-script.md	10-minute presentation/demo script.
Submission checklist	docs/masters/submission-checklist.md	Deliverables and remaining final steps.
Final audit	docs/masters/final-audit-report.md	Consolidated readiness audit and final recommendation.
Demo checklist	docs/masters/manual-demo-checklist.md	Final pre-recording checklist.

Before recording the demo, wake the Render API by opening the API docs, then recheck /api/health with GET.

Features

• Public educational content site with homepage, articles, categories, tags, search, and comments.
• Secure admin panel at /admin.
• JWT authentication with admin, editor, author, and subscriber roles.
• Draft, preview, publish, and archive workflow.
• Rich text posts with SEO fields, categories, tags, and featured images.
• Version history and rollback for content changes.
• Comment moderation with pending, approved, spam, and trash states.
• Media library with validated uploads.
• User management with instant deactivation behavior.
• Dashboard and analytics views.
• Scalar/OpenAPI documentation for the REST API.
• 111 automated workspace tests plus a documented browser QA suite.

Tech Stack

Layer	Technology
Frontend	React, Vite, TypeScript, Tailwind CSS, shadcn/ui
Backend	Node.js, Express.js, TypeScript
Database	PostgreSQL
Shared contract	@educms/shared types, constants, and Zod schemas
Auth	JWT with role-based access control
Frontend hosting	Vercel
API/database hosting	Render and Render PostgreSQL
CI	GitHub Actions

Repository Structure

educms/
  apps/
    web/        # React + Vite public site and admin panel
    api/        # Express REST API
  packages/
    shared/     # Shared types, constants, and Zod schemas
  docs/
    masters/    # Master's checkpoint submission documents

Documentation

Area	Document	Purpose
Architecture	docs/architecture.md	Implementation architecture and data flow.
Database	docs/database.md	Tables, relationships, constraints, indexes, and seed data.
Deployment	docs/deployment.md	Local and cloud deployment notes.
Testing	docs/testing.md	Test strategy, browser QA, and known gaps.
API	docs/api.md	API usage notes and documentation references.
User guide	docs/user-manual.md	Operating guide for users and evaluators.

Local Setup

Requirements:

• Node.js >= 20.19
• npm >= 10
• PostgreSQL >= 15, or Docker for the included Postgres service

Install dependencies:

git clone <repository-url>
cd EduCMS
npm install

Create environment files:

cp apps/api/.env.example apps/api/.env
cp apps/web/.env.example apps/web/.env

Edit apps/api/.env and set at minimum DATABASE_URL and JWT_SECRET. Never commit .env files.

Start local Postgres with Docker:

docker compose up -d postgres

Apply migrations and seed demo data:

npm run migrate -w apps/api
npm run seed -w apps/api

Seed users: admin@educms.local, editor@educms.local, author@educms.local, author2@educms.local, and subscriber@educms.local.

Running the App

Start API and web together:

npm run dev

Or start each workspace separately:

npm run dev:api
npm run dev:web

Local URLs:

Service	URL
Web	http://localhost:5173
API	http://localhost:4000
API health	http://localhost:4000/api/health
API docs	http://localhost:4000/api/docs

Testing

npm run lint
npm run build
npm run test

Latest verified automated test count: 89 API integration tests + 22 web component tests = 111 workspace tests.

Workspace-specific tests:

npm run test -w apps/api    # 89 integration tests; requires migrated + seeded DB
npm run test -w apps/web    # 22 component tests
npm run qa:browser          # Browser QA; requires both dev servers running

CI (.github/workflows/ci.yml) runs lint, build, migrations, seed, backend tests, and frontend tests against a Postgres service container.

API Documentation

Interactive API documentation is served by the API:

Environment	URL
Live API docs	https://educms-api.onrender.com/api/docs
Live OpenAPI JSON	https://educms-api.onrender.com/api/openapi.json
Local API docs	http://localhost:4000/api/docs
Local OpenAPI JSON	http://localhost:4000/api/openapi.json

To test authenticated requests, run POST /auth/login in the docs with a demo account, copy data.token, then paste it as the Bearer token in the Authentication panel.

All API responses use the shared envelope:

{ "success": true, "message": "Success message", "data": {} }

{ "success": false, "message": "Error message", "errors": [] }

Architecture Summary

EduCMS is an npm workspaces monorepo with three main parts:

• apps/web: React/Vite frontend for the public site and admin panel.
• apps/api: Express REST API.
• packages/shared: shared constants, types, and Zod schemas used by both frontend and backend.

Backend request flow:

routes -> middleware -> controllers -> services -> repositories -> PostgreSQL

Important architecture points:

• Public content is served through /api/public and only returns published content.
• Admin and staff workflows require JWT auth and role-based access.
• The API reloads the user from the database on every authenticated request, so deactivation and role changes apply immediately.
• Authors have service-level ownership checks for posts/media.
• Post writes use transactions for post data, tags, and version snapshots.
• Uploads use MIME and magic-byte validation with random stored filenames.

Deployment

The live demo runs on:

Part	Platform	Config
Frontend	Vercel	vercel.json
API	Render	render.yaml
Database	Render PostgreSQL	render.yaml
CI	GitHub Actions	.github/workflows/ci.yml

Frontend deployment:

• Build command: npm run build -w apps/web
• Output directory: apps/web/dist
• Required env: VITE_API_URL=https://<api-host>/api

API deployment:

• Build command: npm ci --include=dev && npm run build -w apps/api && npm run migrate -w apps/api
• Start command: node apps/api/dist/server.js
• Required env: NODE_ENV, DATABASE_URL, JWT_SECRET, FRONTEND_URL

Known Limitations

• Render free-tier services may sleep when idle; first API request can be slow.
• Uploaded files are ephemeral on free-tier filesystem storage unless persistent storage is configured.
• Demo accounts are for evaluation only and should be replaced for real institutional use.
• Browser login/admin smoke test should be run manually before recording the final demo.