Timetable Tracker

A modern, scalable, and production-ready Timetable Tracker designed for students and educators. This application allows users to manage class schedules, track attendance, and analyze performance with an intuitive, classroom-inspired interface. Built with a focus on clean code, domain-driven design, and modern DevOps practices.

Features

• User & Stream Management: Secure user sign-up and sign-in via Google OAuth. Users can create streams or join existing ones using a unique generated code.
• Timetable Creation: Admins can create timetables with specific start and end validity dates.
• Weekly Attendance View: A clear, week-by-week card-based view of the schedule. Students can mark their attendance for each class.
• Admin Controls: Admins have special privileges to globally cancel a class for all students or replace a scheduled class with another from the existing timetable for a specific day.
• Analytics & Calculator:
  • View detailed, subject-wise attendance statistics.
  • A "Manual Override" mode allows users to input attended classes directly to see hypothetical stats.
  • The projection calculator helps users determine how many classes they need to attend (or can skip) to reach a target percentage by a future date.

System Design & Architectural Pattern

The backend is built following a Domain-Driven Design (DDD) approach combined with a Layered Architecture. This creates a system that is robust, maintainable, and scalable.

The Layers of a Domain

Each domain is organized into distinct layers, each with a single responsibility. This is the separation of concerns principle. An HTTP request flows inward through these layers, and the response flows outward.

1. Controller (*.controller.ts) - The Entry Gate
   Job: Handles raw HTTP requests and responses.
   Responsibilities: Extracts data from the request, calls the appropriate Service function, and formats the result from the service into a JSON response with the correct status code.
2. DTO (*.dto.ts) - The Data Contract
   Job: Defines the shape and validation rules for data moving in and out of the application.
   Responsibilities: Uses Zod to create schemas for request bodies, params, and queries. The middleware uses these schemas to ensure all incoming data is valid before it reaches the controller, preventing invalid data from entering the business logic.
3. Service (*.service.ts) - The Brain / Business Logic
   Job: Orchestrates the application's core business rules.
   Responsibilities: Receives validated data from the controller, performs permission checks, executes business logic, calls Repository methods to fetch/save data, and throws specific application errors. This is where the main work happens.
4. Repository (*.repository.ts) - The Database Worker
   Job: Handles all direct communication with the database.
   Responsibilities: It contains all database queries abstracting the data access logic away from the service layer.
5. Prisma Model (schema.prisma) - The Blueprint
   Job: Defines the fundamental data structures and relationships of the domains.
   Responsibilities: Acts as the single source of truth for the database schema. Prisma generates TypeScript types from this file, which are used throughout the application for type safety.