EduTrack — Education Management System

EduTrack is a comprehensive enterprise-grade education management system built with Clean Architecture principles, Domain-Driven Design (DDD), and modern .NET 10 technologies with an Angular frontend. Designed for educational institutions of all sizes, from small schools to large universities.

🎯 Project Vision

Building the next generation of education management software with enterprise-grade architecture, multi-database support, and scalable design patterns.

🎪 Live Demo & Portfolio

🌐 Live Demo: Coming Soon
🏗️ Architecture Documentation: Full guide coming soon. For an immediate overview, please refer to the Developer's Guide and the Clean Architecture Guide

🔥 If this project helps you, please give it a star ⭐ - It means a lot to the team!

🎓 Key Business Features

📚 Student Lifecycle Management — Admission, enrollment, progression, and graduation
🏫 Academic Structure — Departments, programs, courses, and scheduling with conflict detection
👨‍🏫 Faculty Management — Profiles, academic titles, workload tracking, and employment workflows
📊 Grades & Assessments — Flexible grading schemes, assessment weightings, and transcript generation
🔐 Access Control — Role-based and permission-based authorization per user or role
📈 Reporting & Analytics — Dashboards, custom reports, and PDF/Excel/CSV exports

📄 See full business features →

⚙️ Key Technical Features

🏗️ Clean Architecture with Domain-Driven Design and strict layer separation
⚡ CQRS via MediatR — all commands and queries handled through a pipeline
🗄️ Multi-Database Support — PostgreSQL (primary), SQL Server, Oracle, SQLite
🔐 JWT Authentication with role-based and permission-based authorization
🧪 Comprehensive Testing — Domain (≥95%), Application (≥80%), and integration tests
🚀 CI/CD Ready — GitHub Actions, Docker multi-stage builds, OpenAPI/Swagger

📄 See full technical features →

Quick Start Guide

Prerequisites

Before you begin, ensure you have the following installed:

✅ .NET 10 SDK (10.0 or later)
✅ Database Server (choose one):
- PostgreSQL 14+ (Recommended)
✅ Development IDE:
- Visual Studio 2026+ (Recommended)
- VS Code with C# extension
✅ Git for version control
✅ Node.js 18+ (for frontend development)

🗄️ Database Setup

PostgreSQL (Recommended)

1. Install PostgreSQL

Windows: Download the installer from postgresql.org/download or use Chocolatey:
```
choco install postgresql
```
macOS:
```
brew install postgresql
```

Linux (Ubuntu/Debian):

sudo apt install postgresql postgresql-contrib

2. Create the database

creatdb EduTrackDb

Or using psql:

CREATE DATABASE "EduTrackDb";

3. Configure the connection string

Create appsettings.Development.json inside backend/EduTrack/src/EduTrack.Api/ with your credentials:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=EduTrackDb;Username=postgres;Password=yourpassword;"
  }
}

📖 Configure PostgreSQL with pgAdmin 4 — step-by-step guide for setting up the database using the pgAdmin UI.

Other Supported Databases

SQL Server

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=localhost;Database=EduTrackDb;Trusted_Connection=true;MultipleActiveResultSets=true"
  }
}

Oracle

{
  "ConnectionStrings": {
    "DefaultConnection": "User Id=youruser;Password=yourpassword;Data Source=localhost:1521/XEPDB1"
  }
}

🚀 Running the Backend

1. Clone the repository

git clone https://github.com/mahedee/clean-arch-pro.git
cd clean-arch-pro

2. Configure the database connection

Create appsettings.Development.json inside backend/EduTrack/src/EduTrack.Api/ (this file is git-ignored). See the Database Setup section above for connection string examples.

💡 Use appsettings.Production.json as a template.

3. Restore packages

cd backend/EduTrack
dotnet restore

4. Apply database migrations

cd backend/EduTrack/src/EduTrack.Api
dotnet ef database update

If dotnet ef is not found, install it: dotnet tool install --global dotnet-ef

5. Run the API

cd backend/EduTrack/src/EduTrack.Api
dotnet run

URL	Description
`http://localhost:6100`	API base URL
`http://localhost:6100/swagger`	Swagger / OpenAPI UI

Run with a specific launch profile:

dotnet run --launch-profile http        # HTTP only
dotnet run --launch-profile https       # HTTPS + HTTP
dotnet run --launch-profile Staging     # Staging environment
dotnet run --launch-profile Production  # Production environment

Using Visual Studio or VS Code:

Visual Studio: Open backend/EduTrack/EduTrack.sln, select EduTrack.Api, and press F5.
VS Code: Open the backend/EduTrack folder and use the Run and Debug panel (a launch configuration is included in .vscode/).

Troubleshooting

Problem	Fix
`connection refused` on DB	Ensure PostgreSQL is running and credentials are correct in `appsettings.Development.json`
Port 6100 already in use	Change `applicationUrl` in `Properties/launchSettings.json` or stop the conflicting process
Pending migrations error	Run `dotnet ef database update` from the `EduTrack.Api` folder
`dotnet ef` not found	Run `dotnet tool install --global dotnet-ef`

Running the Frontend

1. Install dependencies

cd frontend/edutrack-ui
npm install

2. Start the development server

cd frontend/edutrack-ui
npm start

The app is available at http://localhost:4200. The dev server proxies API calls to http://localhost:6100 (backend must be running). Changes to source files are reflected automatically via hot reload.

Run on a custom port:

ng serve --port 4201

3. Build for production

npm run build
# or:
ng build --configuration production

Output is generated in dist/edutrack-ui/.

4. Run with Server-Side Rendering (SSR)

npm run build
node dist/edutrack-ui/server/server.mjs

5. Run Everything with a Single Script

The easiest way to start both the backend and frontend together is to use the provided PowerShell scripts from the repository root.

Start both applications at once:

.\scripts\run-edutrack-all.ps1

This opens each application in its own terminal window:

Script	What it does
`scripts\run-edutrack-all.ps1`	Launches backend + frontend in separate windows
`scripts\run-edutrack-backend.ps1`	Builds and starts the backend API only
`scripts\run-edutrack-frontend.ps1`	Installs dependencies and starts the Angular dev server only

Once running, the following URLs are available:

URL	Description
`http://localhost:6100`	Backend API
`http://localhost:6100/swagger`	Swagger / OpenAPI UI
`http://localhost:4200`	Angular frontend

Prerequisites: PowerShell 7+ must be installed. .NET 10 SDK and Node.js must be on the system PATH.

Press Ctrl+C in each window to stop the respective application.

Troubleshooting

Problem	Fix
`ng: command not found`	Run `npm install -g @angular/cli`
`npm install` fails	Delete `node_modules/` and `package-lock.json`, then re-run `npm install`
API calls return 404 or CORS errors	Ensure the backend is running on `http://localhost:6100`
Port 4200 already in use	Use `ng serve --port 4201` or stop the conflicting process

🧪 Running Tests

Backend tests

# Run all tests
cd backend/EduTrack
dotnet test

# Run a specific test project
dotnet test tests/EduTrack.Domain.UnitTests/

# Run with code coverage
dotnet test --collect:"XPlat Code Coverage"

See backend unit tests and backend test coverage for details.

Frontend tests

cd frontend/edutrack-ui

# Run tests in watch mode
npm test

# Run tests headless (CI)
npm run test:ci

See frontend unit tests and frontend test coverage for details.

🛠️ Developer Guide

For a full developer reference — including project structure, architecture deep-dive, coding conventions, logging, and configuration — see the Developer's Guide.

📁 Project Structure

The solution follows a four-layer Clean Architecture layout. See Developer's Guide → Project Structure for the full breakdown.

🏗️ Architecture

EduTrack is built on Clean Architecture, DDD, and CQRS. See the Clean Architecture Overview for layer dependencies, design decisions, and key patterns.

✨ Adding a New Feature

Adding a new feature follows a consistent CQRS workflow across Domain → Application → Infrastructure → API → Tests. See the API Implementation Guide for a worked example.

🗄️ Database migrations

# Add a new migration
dotnet ef migrations add "MigrationName" \
  --project src/EduTrack.Infrastructure \
  --startup-project src/EduTrack.Api

# Apply migrations
dotnet ef database update --project src/EduTrack.Api

# Drop database (development only)
dotnet ef database drop --project src/EduTrack.Api --force

🔄 Git Workflow

# Create a feature branch
git checkout -b feature/your-feature-name

# Commit with a descriptive message referencing the issue
git commit -m "Add student CRUD operations - Fixes #18"

# Push and open a pull request
git push origin feature/your-feature-name

See CONTRIBUTING.md and pull request guidelines for the full process.

📝 Coding Conventions

Entities: singular noun — Student, Course
DTOs: suffix with Dto — StudentDto
Interfaces: prefix with I — IStudentRepository
Logging: structured logging via ILogger<T>

🧰 Technology Stack

Backend Technologies

Technology	Version	Purpose	Documentation
.NET	10.0	Core framework	📖 .NET Docs
ASP.NET Core	10.0	Web API framework	📖 ASP.NET Docs
Entity Framework Core	10.0	ORM & Data Access	📖 EF Core Docs
MediatR	12.x	CQRS & Mediator pattern	📖 MediatR
AutoMapper	12.x	Object mapping	📖 AutoMapper
FluentValidation	11.x	Input validation	📖 FluentValidation
Serilog	3.x	Structured logging	📖 Serilog
xUnit	2.x	Unit testing framework	📖 xUnit

Database Support

Database	Status	Performance	Use Case
PostgreSQL	✅ Primary	Excellent	General purpose, JSONB support
SQL Server	✅ Supported	Excellent	Enterprise environments
Oracle	✅ Enterprise	Good	Large enterprise systems
SQLite	🔄 Testing Only	Good	Development & testing

Frontend Technologies

Technology	Version	Purpose
Angular	18.x	Frontend framework
Angular Material	18.x	UI components
TypeScript	5.x	Type safety
RxJS	7.x	Reactive programming

🤝 Contributing

We welcome contributions from developers of all skill levels! Whether you're fixing bugs, adding features, improving documentation, or sharing ideas, your contribution matters. Please read CONTRIBUTING.md before submitting a pull request.

🎯 How to Contribute

🐛 Report Issues

Found a bug or have a suggestion? Please check existing issues first, then:

🔧 Code Contributions

Fork the repository and create your feature branch
Follow our coding standards (see CONTRIBUTING.md)
Write tests for your changes
Submit a pull request following our PR Guidelines

📖 Documentation Contributions

Improve existing documentation
Add code examples and tutorials
Translate documentation to other languages
Create video tutorials or blog posts

🏆 Contributors

Thanks to all the amazing people who have contributed to this project!

📜 License

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

What this means:

✅ Commercial use - Use in commercial projects
✅ Modification - Modify the code as needed
✅ Distribution - Distribute your modifications
✅ Private use - Use privately without restrictions
⚠️ Attribution - Include original license and copyright notice

📞 Support & Community

🆘 Getting Help

📖 Documentation: Check our comprehensive docs first
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: mahedee.hasan@gmail.com

🌟 Show Your Support

If this project helps you build better applications:

⭐ Star the repository on GitHub
🐦 Share on social media (Twitter, LinkedIn)
📝 Write a blog post about your experience
🗣️ Tell your colleagues about EduTrack

📊 Project Stats

📈 GitHub Stars:
🍴 Forks:
👀 Watchers:
📝 Issues:
🔄 Pull Requests:

👨‍💻 About the Maintainer

Mahedee Hasan — Software Architect

🏢 Experience: 17+ years in enterprise software development
🌐 Website: mahedee.net
💼 LinkedIn: linkedin.com/in/mahedee
🐦 Twitter: @mahedee_hasan

🎉 Thank you for choosing EduTrack!

Building the future of education management, one commit at a time.

⭐ Don't forget to star the repository if you found it helpful! ⭐

Name		Name	Last commit message	Last commit date
Latest commit History 89 Commits
.github		.github
.vscode		.vscode
backend/EduTrack		backend/EduTrack
docs		docs
frontend		frontend
scripts		scripts
.editorconfig		.editorconfig
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPER-GUIDE.md		DEVELOPER-GUIDE.md
LICENSE		LICENSE
README.md		README.md
README_bak.md		README_bak.md
SECURITY.md		SECURITY.md
commit-and-push-all.ps1		commit-and-push-all.ps1
commit-and-push-all.sh		commit-and-push-all.sh
pullrequest-guidelines.md		pullrequest-guidelines.md

Folders and files

Latest commit

History

Repository files navigation

EduTrack — Education Management System

📋 Table of Contents

🎯 Project Vision

🎪 Live Demo & Portfolio

🎓 Key Business Features

⚙️ Key Technical Features

Quick Start Guide

Prerequisites

🗄️ Database Setup

PostgreSQL (Recommended)

Other Supported Databases

🚀 Running the Backend

1. Clone the repository

2. Configure the database connection

3. Restore packages

4. Apply database migrations

5. Run the API

Troubleshooting

Running the Frontend

1. Install dependencies

2. Start the development server

3. Build for production

4. Run with Server-Side Rendering (SSR)

5. Run Everything with a Single Script

Troubleshooting

🧪 Running Tests

Backend tests

Frontend tests

🛠️ Developer Guide

📁 Project Structure

🏗️ Architecture

✨ Adding a New Feature

🗄️ Database migrations

🔄 Git Workflow

📝 Coding Conventions

🧰 Technology Stack

Backend Technologies

Database Support

Frontend Technologies

🤝 Contributing

🎯 How to Contribute

🐛 Report Issues

🔧 Code Contributions

📖 Documentation Contributions

🏆 Contributors

📜 License

What this means:

📞 Support & Community

🆘 Getting Help

🌟 Show Your Support

📊 Project Stats

👨‍💻 About the Maintainer

🎉 Thank you for choosing EduTrack!

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages