Kalinga Backend 🏫

A comprehensive RESTful API for school management system built with modern technologies. This backend service handles circulars, timetables, and homework management for educational institutions.

📋 Table of Contents

• Features
• Tech Stack
• Installation
• Environment Setup
• API Documentation
• Database Schema
• Running the Application
• Testing
• Project Structure
• Contributing
• License

✨ Features

• Circular Management: Create, retrieve, and delete school circulars by class
• Timetable Management: Handle class-wise and section-wise timetables
• Homework Management: Manage homework assignments with teacher and student views
• CORS Support: Cross-origin resource sharing enabled
• Data Validation: Comprehensive input validation and error handling
• Type Safety: Full TypeScript implementation
• Database Integration: PostgreSQL with Prisma ORM
• Automatic Timestamps: CreatedAt timestamps for all records
• Case-Insensitive: Flexible class name handling

🛠 Tech Stack

🖥️ Backend Technologies

Technology	Description	Version
	JavaScript runtime environment	18.x+
	Fast web application framework	4.x
	Type-safe JavaScript superset	5.x

🗄️ Database & ORM

Technology	Description	Version
	Advanced open source database	14.x+
	Next-generation ORM toolkit	5.x

📦 Key Dependencies

Package	Purpose	Badge
CORS	Cross-origin resource sharing
dotenv	Environment variable management
Axios	HTTP client for API requests

🚀 Installation

1. Clone the repository

   git clone <repository-url>
   cd kalinga-backend

2. Install dependencies

   npm install

3. Install development dependencies

   npm install -D typescript @types/node @types/express ts-node nodemon

🔧 Environment Setup

1. Create a .env file in the root directory:

   DATABASE_URL="postgresql://username:password@localhost:5432/kalinga_db"
   PORT=3001

2. Setup PostgreSQL database

   • Install PostgreSQL on your system
   • Create a new database named kalinga_db
   • Update the DATABASE_URL with your credentials

3. Run Prisma migrations

   npx prisma migrate dev
   npx prisma generate

📚 API Documentation

Base URL

http://localhost:3001/api

📢 Circulars Endpoints

Create Circular

POST /api/circular
Content-Type: application/json

{
  "url": "https://example.com/circular.pdf",
  "className": "JUNIOR"
}

Get Circulars by Class

GET /api/circular/JUNIOR

Response:

[
  {
    "id": 1,
    "url": "https://example.com/circular.pdf",
    "className": "JUNIOR",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

Delete Circular

DELETE /api/circular/1

📅 Timetable Endpoints

Create Timetable

POST /api/timetable
Content-Type: application/json

{
  "url": "https://example.com/timetable.pdf",
  "className": "Class 5",
  "section": "A"
}

Get Timetable by Class and Section

GET /api/timetable/Class%205/A

Response:

{
  "id": 1,
  "url": "https://example.com/timetable.pdf",
  "className": "Class 5",
  "section": "A",
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Delete Timetable

DELETE /api/timetable/1

📝 Homework Endpoints

Create Homework

POST /api/homework
Content-Type: application/json

{
  "className": "JUNIOR",
  "section": "A",
  "subject": "Mathematics",
  "teacher": "John Doe"
}

Get Homework by Teacher

GET /api/homework/teacher/John%20Doe

Get Homework for Students

GET /api/homework/student/JUNIOR/A

Response:

[
  {
    "id": 1,
    "className": "JUNIOR",
    "section": "A",
    "subject": "Mathematics",
    "teacher": "John Doe",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]

Delete Homework

DELETE /api/homework/1

Error Responses

All endpoints return appropriate HTTP status codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (validation errors)
• 404 - Not Found
• 500 - Internal Server Error

Error response format:

{
  "error": "Error message description"
}

🗄 Database Schema

Circular Table

CREATE TABLE Circular (
  id SERIAL PRIMARY KEY,
  url TEXT NOT NULL,
  className ClassType NOT NULL,
  createdAt TIMESTAMP DEFAULT NOW()
);

Timetable Table

CREATE TABLE Timetable (
  id SERIAL PRIMARY KEY,
  url TEXT NOT NULL,
  className TEXT NOT NULL,
  section TEXT NOT NULL,
  createdAt TIMESTAMP DEFAULT NOW()
);

Homework Table

CREATE TABLE Homework (
  id SERIAL PRIMARY KEY,
  className ClassType NOT NULL,
  section TEXT NOT NULL,
  subject TEXT NOT NULL,
  teacher TEXT NOT NULL,
  createdAt TIMESTAMP DEFAULT NOW()
);

ClassType Enum

CREATE TYPE ClassType AS ENUM ('JUNIOR', 'PRIMARY', 'SENIOR');

🏃‍♂️ Running the Application

Development Mode

npm run dev

The server will start on http://localhost:3001 with auto-reload enabled.

Production Build

npm run build
npm start

Available Scripts

• npm run dev - Run development server with auto-reload
• npm run build - Build TypeScript to JavaScript
• npm run test - Run test suite
• npm start - Start production server

🧪 Testing

Run the comprehensive test suite:

npm run test

Test Coverage

• ✅ All API endpoints functionality
• ✅ Data validation and error handling
• ✅ Database operations
• ✅ Edge cases and boundary conditions
• ✅ HTTP status code validation

📁 Project Structure

kalinga-backend/
├── src/
│   ├── routes/
│   │   ├── circular.ts
│   │   ├── timetable.ts
│   │   └── homework.ts
│   ├── types/
│   │   └── index.ts
│   ├── utils/
│   │   └── database.ts
│   └── app.ts
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── tests/
│   ├── circular.test.ts
│   ├── timetable.test.ts
│   └── homework.test.ts
├── dist/ (generated)
├── .env
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

🤝 Contributing

We welcome contributions to the Kalinga Backend project! Here's how you can help:

Getting Started

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (npm run test)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write comprehensive tests for new features
• Update documentation for API changes
• Use meaningful commit messages
• Ensure code passes all existing tests

Code Style

• Use TypeScript for all new code
• Follow existing naming conventions
• Add appropriate error handling
• Include JSDoc comments for functions

📄 License

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

📞 Support

For support, please contact:

• Email: support@kalinga-backend.com
• Issues: GitHub Issues

---

Made with ❤️ for educational institutions