Attend: Enterprise Attendance System (Backend)

The powerful, scalable, and secure backend for the Attend enterprise attendance system, built for IIIT Kota. This server is engineered with TypeScript and the Hono web framework, running on the Bun runtime for maximum performance. It handles everything from user authentication and role management to real-time attendance session control.

Companion Repository: attend-app (Flutter Client)

Features

• Robust Authentication: Secure Google OAuth 2.0 flow restricted to the iiitkota.ac.in domain. (You can customize for your own domain)
• Role-Based Access Control (RBAC): Differentiated permissions for Admins, Deans, Faculty, and Students.
• Data Management: Full CRUD APIs for managing Students, Faculty, Courses, and Classrooms.
• Real-time Attendance: Create, manage, and update attendance sessions on the fly.
• Bulk Data Upload: Efficiently upload student and faculty data via CSV/TXT files.
• Scalable Architecture: Built on Hono and Bun for high-throughput and low-latency responses.
• Comprehensive API: A well-structured API for the Flutter client to consume.

Architecture Overview

The backend is a monolithic API server responsible for all business logic and data persistence. It authenticates users, manages their roles and sessions, and provides the necessary endpoints for the client application to function.

• Framework: Hono on Bun
• Language: TypeScript
• Database: MongoDB
• Authentication: Google OAuth 2.0 with session tokens

Tech Stack

• Runtime: Bun
• Framework: Hono
• Database: MongoDB (via mongodb driver)
• Authentication: google-auth-library for Google OAuth
• Environment Management: dotenv
• Validation: zod (implicit in Hono)

Getting Started

Prerequisites

• Bun installed on your machine.
• Access to a MongoDB database (local or Atlas).
• Google OAuth 2.0 credentials (Client ID & Client Secret).

Installation

1. Clone the repository:

   git clone https://github.com/s4tyendra/attend.git
   cd attend
   

2. Install dependencies:

   bun install
   

3. Set up environment variables: Create a .env file in the root directory and populate it with the following values. See the .env.example file for a template.

   # Server Configuration
   PORT=3000
   NODE_ENV=development
   
   # MongoDB Configuration
   MONGODB_URI="your_mongodb_connection_string"
   DATABASE_NAME="presenz"
   
   # Google OAuth 2.0 Credentials
   GOOGLE_CLIENT_ID="your_google_client_id.apps.googleusercontent.com"
   GOOGLE_CLIENT_SECRET="your_google_client_secret"
   
   # Session Configuration
   SESSION_TIMEOUT_HOURS=24
   

Running the Server

• Development Mode: This will run the server with hot-reloading.

  bun run dev
  

• Production Mode:

  bun run start
  

The server will be running at http://localhost:3000.

API Endpoints

The server exposes a RESTful API. Here is a high-level overview of the available routes:

Method	Endpoint	Description	Access
GET	/auth/login	Get the Google OAuth login URL.	Public
GET	/auth/callback	Handle Google OAuth callback and create session.	Public
GET	/user/me	Get the current authenticated user's profile.	Authenticated
GET	/classrooms	Get classrooms for the current user.	Authenticated
GET	/classrooms/:id	Get details for a specific classroom.	Member
POST	/attendance/sessions	Create a new attendance session.	Faculty
PUT	/attendance/sessions/:id/mass-update	Mass-update student attendance statuses.	Faculty
GET	/admin/students	Get a list of all students.	Admin/Dean
POST	/admin/upload/students	Bulk upload student data from a file.	Admin
GET	/admin/courses	Get a list of all courses.	Admin
POST	/admin/courses	Create a new course.	Admin

...and many more. Refer to the routes/ directory for a complete list of endpoints.

Project Structure

.
├── src
│   ├── config/         # Environment variables and configuration
│   ├── middleware/     # Custom middleware (auth, error handling)
│   ├── models/         # Database schemas and type definitions
│   ├── routes/         # API route definitions
│   ├── services/       # Core services (database, auth)
│   └── index.ts        # Main server entry point
├── .env.example        # Example environment file
├── package.json
└── tsconfig.json