🎓 AcademiaSync

Smart Learning Management System with OAuth & Role-Based Access Control

A modern, scalable learning platform built with microservices architecture, featuring Google OAuth authentication, real-time analytics, and comprehensive course management.

🚀 Quick Start • ✨ Features • 🏗️ Architecture • 📖 Documentation

🚀 Quick Start

Prerequisites

Docker Desktop - Download & Install
Google OAuth Credentials - Setup Guide
Git - For cloning the repository

Installation

Step 1: Google OAuth Setup

Go to Google Cloud Console
Create a new project or select an existing one
Navigate to APIs & Services → Credentials
Click Create Credentials → OAuth 2.0 Client ID
Configure OAuth consent screen
Set application type to Web application

Add authorized redirect URI:

http://localhost:3000/api/auth/callback/google

Copy your Client ID and Client Secret

Step 2: Clone & Configure

# Clone the repository
git clone https://github.com/heyitsgautham/AcademiaSync.git
cd AcademiaSync

# Copy environment files
cp .env.example .env
cp frontend/.env.example frontend/.env.local

# Edit .env and frontend/.env.local with your Google OAuth credentials

Required Environment Variables:

# .env (root)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=academiasync
DB_PORT=5432
USER_SERVICE_PORT=5000
COURSE_SERVICE_PORT=5001
JWT_SECRET=<your-jwt-secret>
JWT_REFRESH_SECRET=<your-jwt-refresh-secret>
GOOGLE_CLIENT_ID=<your-google-client-id>
GOOGLE_CLIENT_SECRET=<your-google-client-secret>
NEXTAUTH_SECRET=<generate-with-openssl-rand-base64-32>
NEXTAUTH_URL=http://localhost:3000
NEXT_PUBLIC_BACKEND_URL=http://localhost:5000
NEXT_PUBLIC_COURSE_SERVICE_URL=http://localhost:5001
INTERNAL_BACKEND_URL=http://user-service:5000
INTERNAL_COURSE_SERVICE_URL=http://course-service:5001

💡 Generate NEXTAUTH_SECRET: Run openssl rand -base64 32 in terminal

Step 3: Launch with Docker

# Start all services
docker-compose up -d

# Check service health
docker-compose ps

# View logs
docker-compose logs -f

Step 4: Access the Application

Service	URL	Description
🌐 Frontend	http://localhost:3000	Main application
🔧 User Service	http://localhost:5000/health	Auth & user management
🔧 Course Service	http://localhost:5001/health	Courses & assignments
📊 API Docs	http://localhost:5000/api-docs	Swagger documentation

Step 5: Create Admin Account

After first login with Google:

# Access the database
docker exec -it academiasync-db psql -U postgres -d academiasync

# Promote your user to admin (replace with your email)
UPDATE users SET role = 'Admin' WHERE email = 'your-email@gmail.com';
\q

Stopping the Application

# Stop all services
docker-compose down

# Stop and remove volumes (reset database)
docker-compose down -v

✨ Features

🔐 Authentication & Authorization

Google OAuth 2.0 integration via NextAuth.js
JWT-based authentication with access & refresh tokens
Role-based access control (Student, Teacher, Admin)
Secure httpOnly cookies for token storage
Automatic session management and token refresh

👨‍🎓 Student Portal

Dashboard with personalized stats and progress tracking
Course enrollment and management
Assignment submissions with deadline tracking
Analytics dashboard with performance charts
Grade tracking across all courses

👨‍🏫 Teacher Portal

Course creation and management
Assignment creation with due dates
Student management by course
Submission grading with feedback
Analytics for student performance tracking
Recent activity monitoring

👨‍💼 Admin Portal

User management (Students & Teachers)
Role promotion/demotion
Platform-wide analytics
Course oversight
System health monitoring

📊 Analytics & Reporting

Interactive charts using Recharts
Student performance metrics
Course completion rates
Enrollment statistics
Age demographics visualization

🎨 User Experience

Dark/Light theme toggle with persistence
Responsive design for all devices
Toast notifications for user feedback
Confirmation modals for critical actions
Loading states and skeleton screens

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────┐
│                           FRONTEND                                   │
│                    Next.js 14 (App Router)                          │
│            React + TypeScript + TailwindCSS + shadcn/ui             │
│                        Port: 3000                                    │
└─────────────────────────────────────────────────────────────────────┘
                                │
                    ┌───────────┴───────────┐
                    │                       │
                    ▼                       ▼
┌─────────────────────────────┐   ┌─────────────────────────────┐
│       USER SERVICE          │   │      COURSE SERVICE         │
│   Express.js + Node.js      │   │   Express.js + Node.js      │
│        Port: 5000           │   │        Port: 5001           │
│                             │   │                             │
│  • Authentication (OAuth)   │   │  • Course Management        │
│  • User Management          │   │  • Assignment Management    │
│  • Admin Operations         │   │  • Enrollment Management    │
│  • JWT Token Management     │   │  • Submission Management    │
│  • Profile Management       │   │  • Student/Teacher Routes   │
└──────────────┬──────────────┘   └──────────────┬──────────────┘
               │                                  │
               └──────────────┬───────────────────┘
                              │
                              ▼
               ┌─────────────────────────────┐
               │        PostgreSQL 16        │
               │         Port: 5432          │
               │                             │
               │  • Users & Roles            │
               │  • Courses & Enrollments    │
               │  • Assignments              │
               │  • Submissions              │
               │  • Refresh Tokens           │
               └─────────────────────────────┘

Authentication Flow

┌──────────┐     ┌──────────┐     ┌─────────────┐     ┌──────────────┐
│  User    │────▶│ Frontend │────▶│  NextAuth   │────▶│    Google    │
│          │     │  :3000   │     │  OAuth      │     │   OAuth 2.0  │
└──────────┘     └──────────┘     └─────────────┘     └──────────────┘
                                         │
                                         ▼
                              ┌─────────────────┐
                              │  User Service   │
                              │   POST /auth/   │
                              │  google-signin  │
                              └────────┬────────┘
                                       │
                                       ▼
                              ┌─────────────────┐
                              │   JWT Tokens    │
                              │  (Access +      │
                              │   Refresh)      │
                              └─────────────────┘

Docker Network

All services communicate via the academiasync-network bridge network:

Container	Internal Hostname	External Port
Frontend	`frontend`	3000
User Service	`user-service`	5000
Course Service	`course-service`	5001
PostgreSQL	`db`	5432

🛠️ Tech Stack

Frontend

Technology	Purpose	Version
	React Framework (App Router)	14.x
	Type Safety	5.0.x
	UI Library	18.x
	Styling	3.4.x
	UI Components	Latest
	Server State Management	5.64.x
	Authentication	4.x
	Data Visualization	2.x
	Form Management	7.x
	Schema Validation	1.x
	Theme Management	0.3.x

Backend

Technology	Purpose	Version
	Runtime Environment	20.x
	Web Framework	4.x
	Database	16.x
	Token Authentication	9.x
	OAuth 2.0	9.x
	HTTP Logging	1.10.x
	API Documentation	5.x

DevOps & Infrastructure

Technology	Purpose	Version
	Containerization	24.x
	Orchestration	2.x
	Infrastructure as Code	1.5.x
	Container Orchestration	Latest
	Container Registry	Latest
	CI/CD Pipeline	Latest
	Testing Framework	29.x

📁 Project Structure

AcademiaSync/
├── 📁 frontend/                      # Next.js Application
│   ├── 📁 app/                       # App Router pages
│   │   ├── layout.tsx                # Root layout with providers
│   │   ├── page.tsx                  # Landing page
│   │   ├── 📁 api/                   # API route handlers
│   │   │   ├── 📁 auth/[...nextauth] # OAuth configuration
│   │   │   ├── 📁 student/           # Student API routes
│   │   │   ├── 📁 teacher/           # Teacher API routes
│   │   │   └── 📁 admin/             # Admin API routes
│   │   ├── 📁 student/               # Student dashboard pages
│   │   ├── 📁 teacher/               # Teacher dashboard pages
│   │   └── 📁 admin/                 # Admin dashboard pages
│   ├── 📁 components/                # React components (60+)
│   │   ├── 📁 ui/                    # shadcn/ui base components
│   │   ├── student-*.tsx             # Student-specific components
│   │   ├── teacher-*.tsx             # Teacher-specific components
│   │   └── admin-*.tsx               # Admin-specific components
│   ├── 📁 lib/                       # Utilities & API client
│   ├── 📁 types/                     # TypeScript definitions
│   ├── middleware.ts                 # Route protection
│   └── Dockerfile                    # Multi-stage build
│
├── 📁 backend/
│   ├── 📁 user-service/              # Auth & User Management
│   │   ├── 📁 src/
│   │   │   ├── 📁 routes/            # API endpoints
│   │   │   │   ├── auth.js           # OAuth & JWT
│   │   │   │   ├── admin.js          # Admin operations
│   │   │   │   ├── dashboard.js      # Dashboard data
│   │   │   │   └── users.js          # User CRUD
│   │   │   ├── 📁 middleware/        # Auth & authorization
│   │   │   └── 📁 utils/             # HATEOAS, logging
│   │   ├── 📁 tests/                 # Jest test suites
│   │   └── Dockerfile
│   │
│   ├── 📁 course-service/            # Courses & Assignments
│   │   ├── 📁 src/
│   │   │   ├── 📁 routes/
│   │   │   │   ├── courses.js        # Course CRUD
│   │   │   │   ├── assignments.js    # Assignment CRUD
│   │   │   │   ├── student.js        # Student operations
│   │   │   │   ├── teacher.js        # Teacher operations
│   │   │   │   └── analytics.js      # Analytics data
│   │   │   └── 📁 middleware/
│   │   ├── 📁 tests/
│   │   └── Dockerfile
│   │
│   └── 📁 database/
│       ├── init.sql                  # Schema initialization
│       └── seed-demo-data.sql        # Demo data
│
├── 📁 terraform/                     # AWS Infrastructure
│   ├── main.tf                       # Root module
│   ├── variables.tf                  # Variable definitions
│   ├── outputs.tf                    # Output values
│   ├── 📁 modules/
│   │   ├── vpc/                      # VPC & networking
│   │   ├── ecr/                      # Container registry
│   │   ├── ecs/                      # ECS cluster & services
│   │   ├── cloudwatch/               # Monitoring
│   │   └── sns/                      # Notifications
│   └── deploy.sh                     # Deployment script
│
├── 📁 .github/workflows/             # CI/CD Pipelines
│   ├── ci.yml                        # Test suite
│   ├── docker-build-push.yml         # Build & push to ECR
│   └── terraform-deploy.yml          # Infrastructure deployment
│
├── 📁 deployment/                    # Deployment scripts
│   ├── deploy.sh
│   ├── init-db.sh
│   └── setup-supabase.sql
│
├── 📁 docs/                          # Additional documentation
│   ├── AWS_CONSOLE_GUIDE.md
│   └── AWS_OAUTH_FIX_EXPLAINED.md
│
├── docker-compose.yml                # Local development
├── .env.example                      # Environment template
└── README.md                         # This file

📚 API Documentation

User Service (Port 5000)

Method	Endpoint	Description	Auth
`POST`	`/auth/google-signin`	Google OAuth sign-in	Public
`POST`	`/auth/refresh`	Refresh access token	Cookie
`POST`	`/auth/logout`	Logout user	JWT
`GET`	`/profile`	Get user profile	JWT
`PUT`	`/profile`	Update profile	JWT
`GET`	`/admin/teachers`	List all teachers	Admin
`POST`	`/admin/teachers`	Create teacher	Admin
`PUT`	`/admin/teachers/:id`	Update teacher	Admin
`DELETE`	`/admin/teachers/:id`	Delete teacher	Admin
`GET`	`/admin/students`	List all students	Admin
`PUT`	`/admin/promote-role`	Change user role	Admin
`GET`	`/dashboard/stats`	Dashboard statistics	JWT
`GET`	`/health`	Service health check	Public

Course Service (Port 5001)

Method	Endpoint	Description	Auth
Courses
`GET`	`/courses`	List all courses	JWT
`POST`	`/courses`	Create course	Teacher
`PUT`	`/courses/:id`	Update course	Teacher
`DELETE`	`/courses/:id`	Delete course	Teacher
Assignments
`GET`	`/assignments/course/:id`	Get course assignments	JWT
`POST`	`/assignments`	Create assignment	Teacher
`PUT`	`/assignments/:id`	Update assignment	Teacher
`DELETE`	`/assignments/:id`	Delete assignment	Teacher
Student Routes
`GET`	`/student/courses`	Get enrolled courses	Student
`POST`	`/student/enroll`	Enroll in course	Student
`GET`	`/student/assignments`	Get assignments	Student
`POST`	`/student/submit`	Submit assignment	Student
Teacher Routes
`GET`	`/teacher/courses`	Get teacher's courses	Teacher
`GET`	`/teacher/students/:courseId`	Get course students	Teacher
`GET`	`/teacher/submissions`	Get submissions	Teacher
`PUT`	`/teacher/grade/:submissionId`	Grade submission	Teacher
Analytics
`GET`	`/analytics/student`	Student analytics	Student
`GET`	`/analytics/teacher`	Teacher analytics	Teacher
`GET`	`/analytics/admin`	Platform analytics	Admin
`GET`	`/health`	Service health check	Public

Swagger Documentation

Access interactive API documentation at: http://localhost:5000/api-docs

🗄️ Database Schema

Entity Relationship Diagram

┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
│     users       │       │    courses      │       │   assignments   │
├─────────────────┤       ├─────────────────┤       ├─────────────────┤
│ id (PK)         │       │ id (PK)         │       │ id (PK)         │
│ email           │◄──────│ teacher_id (FK) │       │ course_id (FK)  │──┐
│ google_id       │       │ title           │◄──────│ title           │  │
│ password_hash   │       │ description     │       │ description     │  │
│ role            │       │ weeks           │       │ due_date        │  │
│ first_name      │       │ created_at      │       │ created_at      │  │
│ last_name       │       │ updated_at      │       │ updated_at      │  │
│ age             │       └─────────────────┘       └─────────────────┘  │
│ specialization  │                                          │           │
│ profile_picture │       ┌─────────────────┐       ┌───────┴───────────┴──┐
│ created_at      │       │   enrollments   │       │    submissions       │
│ updated_at      │       ├─────────────────┤       ├──────────────────────┤
└────────┬────────┘       │ id (PK)         │       │ id (PK)              │
         │                │ student_id (FK) │──┐    │ assignment_id (FK)   │
         │                │ course_id (FK)  │  │    │ student_id (FK)      │──┐
         │                │ enrolled_at     │  │    │ submission_text      │  │
         │                └─────────────────┘  │    │ submitted_at         │  │
         │                        ▲            │    │ grade                │  │
         │                        │            │    │ feedback             │  │
         └────────────────────────┴────────────┴────┴──────────────────────┘
                                                    │
┌─────────────────┐                                 │
│ refresh_tokens  │                                 │
├─────────────────┤                                 │
│ id (PK)         │                                 │
│ user_id (FK)    │◄────────────────────────────────┘
│ token           │
│ expires_at      │
│ created_at      │
└─────────────────┘

Tables Overview

Table	Description	Key Fields
`users`	All platform users	role: Student/Teacher/Admin
`courses`	Course catalog	teacher_id links to creator
`enrollments`	Student-course mapping	Unique constraint on student+course
`assignments`	Course assignments	course_id links to parent course
`submissions`	Student submissions	grade & feedback fields
`refresh_tokens`	JWT refresh tokens	Auto-expires

🚀 Deployment

Local Development (Docker Compose)

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

AWS Production Deployment

The application is deployable to AWS ECS Fargate using Terraform:

┌─────────────────────────────────────────────────────────────────┐
│                        AWS Cloud                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │                         VPC                               │   │
│  │  ┌─────────────────┐    ┌─────────────────┐             │   │
│  │  │  Public Subnet  │    │  Public Subnet  │             │   │
│  │  │     (AZ-1)      │    │     (AZ-2)      │             │   │
│  │  └────────┬────────┘    └────────┬────────┘             │   │
│  │           │                      │                        │   │
│  │           └──────────┬───────────┘                        │   │
│  │                      │                                    │   │
│  │              ┌───────▼───────┐                           │   │
│  │              │      ALB      │                           │   │
│  │              │ (Load Balancer)│                          │   │
│  │              └───────┬───────┘                           │   │
│  │                      │                                    │   │
│  │    ┌─────────────────┼─────────────────┐                 │   │
│  │    │                 │                 │                 │   │
│  │    ▼                 ▼                 ▼                 │   │
│  │ ┌──────┐       ┌──────────┐     ┌───────────┐          │   │
│  │ │ ECS  │       │   ECS    │     │    ECS    │          │   │
│  │ │Front │       │  User    │     │  Course   │          │   │
│  │ │ end  │       │ Service  │     │  Service  │          │   │
│  │ └──────┘       └──────────┘     └───────────┘          │   │
│  │                                                          │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐       │
│  │   ECR    │  │CloudWatch│  │   SNS    │  │ Secrets  │       │
│  │ Registry │  │  Logs    │  │  Alerts  │  │ Manager  │       │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘       │
└─────────────────────────────────────────────────────────────────┘

Deployment Commands

cd terraform

# Initialize Terraform
terraform init

# Preview changes
terraform plan

# Deploy infrastructure
terraform apply

# Destroy infrastructure
terraform destroy

See terraform/README.md for detailed deployment instructions.

🔄 CI/CD Pipeline

GitHub Actions Workflows

1. CI Pipeline (`ci.yml`)

Triggers: Push to main/develop, Pull requests
Jobs:
- Test User Service
- Test Course Service
- Build Frontend

2. Docker Build & Push (`docker-build-push.yml`)

Triggers: Changes to app-deployment/**
Jobs:
- Detect changed services
- Build Docker images
- Run security scans (Trivy)
- Push to AWS ECR

3. Terraform Deploy (`terraform-deploy.yml`)

Triggers: Changes to terraform/**
Jobs:
- Validate Terraform
- Plan infrastructure changes
- Apply changes (manual approval)

Pipeline Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│    Push to   │────▶│   Run CI     │────▶│   Build &    │
│    main      │     │   Tests      │     │   Push ECR   │
└──────────────┘     └──────────────┘     └──────────────┘
                                                  │
                                                  ▼
                     ┌──────────────┐     ┌──────────────┐
                     │   Deploy     │◀────│  Terraform   │
                     │   to ECS     │     │    Apply     │
                     └──────────────┘     └──────────────┘

⚙️ Environment Configuration

Required Environment Variables

Root `.env`

# Database
POSTGRES_USER=postgres
POSTGRES_PASSWORD=postgres
POSTGRES_DB=academiasync
DB_PORT=5432

# Services
USER_SERVICE_PORT=5000
COURSE_SERVICE_PORT=5001

# JWT
JWT_SECRET=<your-jwt-secret>
JWT_REFRESH_SECRET=<your-jwt-refresh-secret>
JWT_ACCESS_EXPIRY=15m
JWT_REFRESH_EXPIRY=7d

# OAuth
GOOGLE_CLIENT_ID=<your-google-client-id>
GOOGLE_CLIENT_SECRET=<your-google-client-secret>

# NextAuth
NEXTAUTH_SECRET=<generate-with-openssl>
NEXTAUTH_URL=http://localhost:3000

# Service URLs (external)
NEXT_PUBLIC_BACKEND_URL=http://localhost:5000
NEXT_PUBLIC_COURSE_SERVICE_URL=http://localhost:5001

# Service URLs (internal Docker network)
INTERNAL_BACKEND_URL=http://user-service:5000
INTERNAL_COURSE_SERVICE_URL=http://course-service:5001

Production (AWS)

For production deployment, store secrets in AWS Secrets Manager and reference them in terraform.tfvars:

# terraform/terraform.tfvars
nextauth_secret      = "aws-secrets-manager-arn"
google_client_id     = "your-client-id"
google_client_secret = "aws-secrets-manager-arn"
jwt_secret           = "aws-secrets-manager-arn"
database_url         = "postgresql://..."

📖 Documentation

Additional Resources

Document	Description
AWS Console Guide	AWS setup walkthrough
AWS OAuth Fix	OAuth troubleshooting
Terraform README	Infrastructure deployment
Copilot Instructions	Development conventions

Key Architecture Decisions

Microservices Architecture: Separation of user management and course management for independent scaling
JWT + OAuth: Hybrid authentication for security and user convenience
Docker Compose for Dev: Consistent local development environment
Terraform for Prod: Infrastructure as Code for reproducible deployments
Next.js App Router: Modern React patterns with server components
shadcn/ui: Accessible, customizable UI components

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow the Copilot Instructions for coding conventions
Always use Docker for running services
Write tests for new features
Update documentation as needed

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🎓 Built with ❤️ for Education

AcademiaSync - Empowering Teachers, Inspiring Students

⬆ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
.github/workflows		.github/workflows
app-deployment		app-deployment
backend		backend
deployment		deployment
frontend		frontend
terraform		terraform
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
deploy.sh		deploy.sh
docker-compose.yml		docker-compose.yml

Folders and files

Latest commit

History

Repository files navigation

🎓 AcademiaSync

Smart Learning Management System with OAuth & Role-Based Access Control

📋 Table of Contents

🚀 Quick Start

Prerequisites

Installation

Step 1: Google OAuth Setup

Step 2: Clone & Configure

Step 3: Launch with Docker

Step 4: Access the Application

Step 5: Create Admin Account

Stopping the Application

✨ Features

🔐 Authentication & Authorization

👨‍🎓 Student Portal

👨‍🏫 Teacher Portal

👨‍💼 Admin Portal

📊 Analytics & Reporting

🎨 User Experience

🏗️ Architecture

System Overview

Authentication Flow

Docker Network

🛠️ Tech Stack

Frontend

Backend

DevOps & Infrastructure

📁 Project Structure

📚 API Documentation

User Service (Port 5000)

Course Service (Port 5001)

Swagger Documentation

🗄️ Database Schema

Entity Relationship Diagram

Tables Overview

🚀 Deployment

Local Development (Docker Compose)

AWS Production Deployment

Deployment Commands

🔄 CI/CD Pipeline

GitHub Actions Workflows

1. CI Pipeline (ci.yml)

2. Docker Build & Push (docker-build-push.yml)

3. Terraform Deploy (terraform-deploy.yml)

Pipeline Flow

⚙️ Environment Configuration

Required Environment Variables

Root .env

Production (AWS)

📖 Documentation

Additional Resources

Key Architecture Decisions

🤝 Contributing

Development Guidelines

📄 License

🎓 Built with ❤️ for Education

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. CI Pipeline (`ci.yml`)

2. Docker Build & Push (`docker-build-push.yml`)

3. Terraform Deploy (`terraform-deploy.yml`)

Root `.env`

Packages