git clone https://github.com/chigemezu2202/classroom-backend.git
cd classroom-backend

2. Install Dependencies

npm install

3. Environment Configuration

Create a .env file in the root directory with the following variables:

DATABASE_URL=your_neon_database_url_here
PORT=3000
FRONTEND_URL=http://localhost:5173

Note: The FRONTEND_URL defaults to http://localhost:5173 if not specified.

4. Database Setup

Generate and run database migrations:

npm run db:generate  # Generate migration files
npm run db:migrate   # Apply migrations to database
npm run db:seed      # Seed initial data (optional)

5. Start Development Server

npm run dev

The server will start and listen on the port specified in your .env file (default: 3000).

Output:

Server started and listening on http://localhost:3000

📦 Available Scripts

🔌 API Endpoints

Base URL

http://localhost:3000/api

Root Endpoint

GET /

• Returns a welcome message
• Response: { message: "Hello from TypeScript Express server!" }

Subjects Endpoints

Get All Subjects

GET /api/subjects

Retrieve all subjects with advanced filtering, search, and pagination capabilities.

Query Parameters:

• search (optional, string): Search subjects by name or code (case-insensitive)
• department (optional, string): Filter by department name (case-insensitive)
• page (optional, number): Page number (default: 1, minimum: 1)
• limit (optional, number): Items per page (default: 10, maximum: 100)

Example Request:

GET /api/subjects?search=mathematics&department=science&page=1&limit=10

Response:

{
  "data": [
    {
      "id": 1,
      "departmentId": 2,
      "name": "Calculus",
      "code": "MATH101",
      "description": "Introduction to Calculus",
      "created_at": "2026-03-15T10:30:00Z",
      "updated_at": "2026-03-15T10:30:00Z",
      "department": {
        "id": 2,
        "code": "SCI",
        "name": "Science",
        "description": "Science Department",
        "created_at": "2026-03-15T10:30:00Z",
        "updated_at": "2026-03-15T10:30:00Z"
      }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

Status Codes:

• 200 OK: Successfully retrieved subjects
• 500 Internal Server Error: Server error occurred

📊 Database Schema

Departments Table

Subjects Table

Relationships:

• One Department has Many Subjects
• Each Subject belongs to one Department
• Foreign key constraint with RESTRICT on delete

🔐 CORS Configuration

The API is configured with CORS to allow frontend applications to make requests:

Allowed Origins:

• Frontend URL from FRONTEND_URL env variable
• Default: http://localhost:5173 (Vite development server)

Allowed Methods: GET, POST, PUT, DELETE

Credentials: Enabled

Configure the FRONTEND_URL in your .env file to restrict API access to authorized frontend domains.

📁 Project Structure

classroom-backend/
├── src/
│   ├── index.ts                 # Express app initialization
│   ├── db/
│   │   ├── index.ts            # Database client configuration
│   │   └── schema/
│   │       ├── index.ts        # Schema exports
│   │       └── app.ts          # Database tables & relationships
│   └── routes/
│       └── subjects.ts         # Subjects API endpoints
├── drizzle/                     # Database migrations
├── drizzle.config.ts           # Drizzle ORM configuration
├── tsconfig.json               # TypeScript configuration
├── package.json                # Project dependencies
├── .env                        # Environment variables (gitignored)
├── .env.example                # Example environment variables
└── README.md                   # This file

🔄 Data Flow

1. Request → Express middleware processes request (CORS, JSON parser)
2. Routing → Request routed to appropriate handler (/api/subjects)
3. Database Query → Drizzle ORM constructs and executes SQL query
4. Response → Data formatted and returned with pagination metadata
5. Error Handling → Errors caught and returned with appropriate status codes

⚠️ Error Handling

The API includes comprehensive error handling:

• Invalid pagination parameters are normalized (negative values default to minimum)
• Limit is capped at 100 items per page for performance
• Missing or invalid database connections return 500 errors
• Search and filter operations are case-insensitive and safe from SQL injection (via ORM)

🔧 Development Workflow

1. Make changes to TypeScript files in src/
2. Development server automatically recompiles with npm run dev
3. Test changes against the running API
4. Commit changes to version control
5. Build for production with npm run build

📝 Environment Variables

🤝 Contributing

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

📄 License

This project is licensed under the ISC License - see the package.json file for details.

📞 Support & Contact

For issues, questions, or suggestions, please open an issue on the GitHub repository.

🎯 Future Enhancements

• User authentication and authorization
• Additional CRUD operations for departments and subjects
• Advanced query capabilities and filtering
• Rate limiting and request throttling
• Comprehensive API documentation (Swagger/OpenAPI)
• Unit and integration tests
• API versioning
• Caching strategies
• Logging and monitoring

📚 Additional Resources

• Express.js Documentation
• TypeScript Documentation
• Drizzle ORM Documentation
• Neon PostgreSQL Documentation

Last Updated: May 2026
Version: 1.0.0

Classroom Backend Documentation

Features

• User authentication and authorization
• Course management
• Assignment submissions and grading
• Real-time notifications
• API support for third-party integrations

Tech Stack

• Backend: Node.js, Express
• Database: MongoDB
• Authentication: JWT (JSON Web Token)
• Real-time Communication: Socket.io
• Server: hosted on Heroku

Setup Instructions

1. Clone the repository:

   git clone https://github.com/chigemezu2202/classroom-backend.git
   cd classroom-backend
   

2. Install dependencies:

   npm install
   

3. Set up environment variables in a .env file:

   PORT=your_port
   MONGO_URI=your_mongo_uri
   JWT_SECRET=your_jwt_secret
   

4. Start the application:

   npm start
   

API Endpoints

Database Schema

• Users: { id, username, password, email, created_at }
• Courses: { id, title, description, created_by, created_at }
• Assignments: { id, title, description, due_date, course_id }

CORS Configuration

const cors = require('cors');
app.use(cors({
  origin: 'your_origin',
  methods: 'GET,POST,PUT,DELETE',
}));

Project Structure

classroom-backend/
├── config/          # configuration files
├── controllers/     # request handlers
├── models/          # database models
├── routes/          # API endpoints
├── middleware/      # authentication middleware
├── utils/           # utility functions
└── server.js        # entry point

Error Handling

• Use try-catch blocks to handle errors.
• Return appropriate status codes and messages based on error type.

Future Enhancements

• Implement a notification system for course updates.
• Add payment integrations for premium features.
• Enhance security measures for user data protection.

mock_api_backend

A TypeScript-based tool that simplifies the creation and management of mock APIs for your development and testing needs