Part 1 — Project Introduction (README.md)

🏢 CoWork API

A Robust Multi-Tenant Coworking Space Booking Platform

Production-inspired REST API built with FastAPI, designed for secure room booking, conflict prevention, refund calculation, role-based authorization, and concurrent request handling.

---

---

📖 Overview

CoWork API is a secure, multi-tenant backend service that powers a coworking space reservation platform.

The project allows organizations to manage rooms while enabling members to create, view, and cancel bookings under a strict set of business rules. The system focuses on correctness, predictable API behavior, and safe handling of concurrent requests.

Unlike a simple CRUD application, this project enforces real-world booking constraints including:

• preventing overlapping reservations
• enforcing booking quotas
• automatic refund calculation
• organization isolation
• role-based authorization
• JWT authentication
• booking reference generation
• pagination
• usage reporting
• CSV export
• concurrent request protection

The entire application is implemented as a RESTful API using FastAPI and follows a layered architecture that separates routers, services, authentication, persistence, and utility modules.

---

✨ Key Highlights

• 🏢 Multi-tenant organization support
• 🔐 JWT Authentication (Access + Refresh Tokens)
• 👤 Role-based Authorization (Admin / Member)
• 📅 Room Booking Management
• 🚫 Conflict Detection
• 💰 Automatic Pricing
• 💵 Refund Calculation
• 📊 Room Statistics
• 📈 Usage Reports
• 📄 CSV Export
• ⚡ Pagination
• 🔒 Thread-safe Booking Operations
• 🚀 Docker Support
• 📚 Interactive Swagger Documentation
• 🧩 Modular Service Architecture

---

🎯 Objectives

The primary goal of this project is to implement a booking platform that satisfies a comprehensive business specification while maintaining a stable public API contract.

Special attention has been given to:

• Business Rule Enforcement
• API Consistency
• Concurrent Request Safety
• Security
• Data Integrity
• Clean Code Organization
• Predictable Error Handling
• Maintainability

---

🚀 Features

Authentication

• Organization registration
• Automatic organization creation
• Member onboarding
• JWT Access Token
• Refresh Token
• Token Rotation
• Logout with Token Revocation

---

Room Management

• Create rooms
• List organization rooms
• Room availability lookup
• Live room statistics

---

Booking Management

• Create booking
• Booking validation
• Booking conflict detection
• Booking listing
• Booking details
• Booking cancellation
• Automatic pricing
• Booking reference generation

---

Administration

• Organization usage report
• CSV export
• Organization-wide booking visibility
• Revenue reporting

---

Reliability

The project includes protections against several common backend consistency issues:

• Overlapping room reservations
• Duplicate booking references
• Duplicate refund creation
• Cross-room quota race conditions
• Concurrent booking conflicts
• Concurrent cancellation races
• Organization data leakage

---

🧠 Design Philosophy

This project was intentionally designed with correctness before complexity.

Instead of relying on unnecessary abstractions, the implementation emphasizes:

• explicit business rule enforcement
• predictable request lifecycle
• clear separation of responsibilities
• minimal API surface
• defensive validation
• readable service organization

The goal is to make the codebase understandable, maintainable, and easy to verify while preserving the required API contract.

---

📌 Project Scope

The API provides everything required to support a coworking booking platform:

• User Authentication
• Organization Management
• Room Management
• Booking Engine
• Refund Engine
• Reporting
• Export
• Statistics
• Authorization
• Validation
• Pagination
• Concurrency Protection

while maintaining complete isolation between organizations.

---

🏗 Technology Stack

Category	Technology
Language	Python 3.11
Framework	FastAPI
Database	SQLite
ORM	SQLAlchemy
Authentication	JWT
Validation	Pydantic
API Docs	Swagger UI
Containerization	Docker
Server	Uvicorn

---

📚 Documentation

This README covers:

• Project Overview
• Architecture
• Folder Structure
• Installation
• Configuration
• Authentication Flow
• API Endpoints
• Business Rules
• Concurrency Strategy
• Error Handling
• Testing
• Deployment
• Future Improvements

Continue reading below for the complete documentation.

---

🏗 System Architecture

The application follows a layered architecture that separates responsibilities across routers, services, authentication, persistence, and utilities.

                Client
                   │
                   ▼
            FastAPI Router Layer
                   │
        ┌──────────┴──────────┐
        │                     │
 Authentication         Business Logic
        │                     │
        ▼                     ▼
    Services Layer       Validation Layer
        │                     │
        └──────────┬──────────┘
                   ▼
             SQLAlchemy ORM
                   │
                   ▼
               SQLite Database

Each layer has a single responsibility:

Layer	Responsibility
Routers	HTTP endpoints and request handling
Auth	JWT creation, verification and authorization
Services	Business logic and reusable operations
Models	Database entities
Schemas	Request/Response validation
Database	Session management
Utilities	Datetime helpers, caching, statistics

---

📂 Project Structure

app/
│
├── main.py
├── database.py
├── models.py
├── schemas.py
├── auth.py
├── config.py
├── errors.py
├── timeutils.py
│
├── routers/
│   ├── auth.py
│   ├── rooms.py
│   ├── bookings.py
│   └── admin.py
│
├── services/
│   ├── cache.py
│   ├── export.py
│   ├── notifications.py
│   ├── ratelimit.py
│   ├── reference.py
│   ├── refunds.py
│   └── stats.py
│
└── requirements.txt

---

📌 Folder Responsibilities

routers/

Contains all REST API endpoints.

Each router focuses on one bounded domain.

• Authentication
• Rooms
• Bookings
• Administration

Routers contain minimal business logic and delegate complex operations to services.

---

services/

Contains reusable business components.

Examples:

• Booking reference generation
• Refund calculation
• CSV export
• Statistics
• Rate limiting
• Notifications
• Cache helpers

Keeping these operations isolated makes the routers significantly cleaner.

---

auth.py

Responsible for

• JWT generation
• JWT validation
• Refresh token handling
• Token revocation
• Role verification

---

schemas.py

Defines every request and response model using Pydantic.

Examples:

• RegisterRequest
• LoginRequest
• RoomCreateRequest
• BookingCreateRequest

Validation happens before requests reach the business logic.

---

models.py

Defines SQLAlchemy ORM models.

Current entities include:

• User
• Room
• Booking
• RefundLog

---

database.py

Initializes the SQLAlchemy engine, session factory, and database connection.

The project currently uses SQLite for simplicity and portability.

---

🔄 Request Lifecycle

Every request follows the same lifecycle.

HTTP Request

      │

      ▼

FastAPI Router

      │

Authentication

      │

Authorization

      │

Validation

      │

Business Rules

      │

Database

      │

Response Serialization

      │

HTTP Response

This predictable pipeline keeps responsibilities separated and simplifies debugging.

---

🔐 Authentication Flow

Register

      │

Login

      │

Access Token
Refresh Token

      │

Bearer Authentication

      │

Protected Endpoints

      │

Logout

      │

Access Token Revoked

---

📅 Booking Flow

Create Booking

        │

Validate Request

        │

Validate Datetimes

        │

Validate Room

        │

Rate Limit Check

        │

Quota Check

        │

Conflict Detection

        │

Price Calculation

        │

Reference Generation

        │

Persist Booking

        │

Update Statistics

        │

Invalidate Cache

        │

Return Booking

---

❌ Cancellation Flow

Cancel Booking

        │

Ownership Check

        │

Booking Lock

        │

Refund Calculation

        │

Refund Log

        │

Update Booking Status

        │

Update Statistics

        │

Invalidate Cache

        │

Return Refund

---

🔄 Concurrency Strategy

Several endpoints perform state-changing operations.

To preserve correctness during concurrent requests, lightweight in-memory synchronization is used.

Current synchronization points include:

• Room-level booking lock
• User-level quota lock
• Booking-level cancellation lock
• Reference code generation lock

These guards ensure business rules remain consistent even when multiple requests arrive simultaneously.

---

🛡 Multi-Tenant Isolation

Every organization owns its own resources.

The application guarantees that:

• Members cannot access another organization's rooms.
• Admins only manage their own organization.
• Reports are organization scoped.
• Room availability is organization scoped.
• Booking visibility is organization scoped.

Every database query involving protected resources applies organization filtering before returning data.

---

📈 Scalability Notes

Although this project uses SQLite for the challenge, the architecture intentionally keeps the database layer isolated.

Migrating to PostgreSQL or MySQL would primarily require updating the SQLAlchemy configuration rather than changing application logic.

The service-oriented design also allows additional features such as email notifications, payment gateways, or distributed caching to be integrated with minimal changes.

🚀 Getting Started

Prerequisites

Before running the project, ensure you have:

• Python 3.11+
• Docker Desktop (recommended)
• Git
• pip

---

📥 Clone Repository

git clone https://github.com/<your-username>/<repository>.git

cd <repository>

---

🐳 Running with Docker (Recommended)

Build and start the application.

docker compose up --build

Run in detached mode.

docker compose up -d

Stop containers.

docker compose down

Rebuild after code changes.

docker compose up --build

---

💻 Running Locally

Create a virtual environment.

Windows

python -m venv .venv

.venv\Scripts\activate

Linux / macOS

python -m venv .venv

source .venv/bin/activate

---

Install dependencies.

pip install -r requirements.txt

---

Run FastAPI.

uvicorn app.main:app --reload

Server

http://localhost:8000

---

Swagger UI

http://localhost:8000/docs

---

OpenAPI Schema

http://localhost:8000/openapi.json

---

⚙ Environment Configuration

The project currently uses a lightweight configuration suitable for the hackathon environment.

Main configuration includes:

• JWT Secret
• Token expiration
• Database URL
• SQLite configuration

Future deployments can externalize these values using environment variables.

---

🗄 Database

Current database engine:

SQLite

ORM:

SQLAlchemy

Tables are created automatically during application startup.

No manual migration step is required.

---

🔐 Authentication

Protected endpoints require a Bearer token.

Example

Authorization: Bearer <access_token>

Authentication flow:

Register

↓

Login

↓

Receive Tokens

↓

Call Protected APIs

↓

Logout

↓

Token Revoked

---

📚 Interactive Documentation

Swagger UI

/docs

OpenAPI JSON

/openapi.json

Both are automatically generated from FastAPI.

---

🧪 Example Development Workflow

git clone ...

docker compose up --build

Open:

http://localhost:8000/docs

Register

↓

Login

↓

Copy Access Token

↓

Authorize

↓

Test Endpoints

---

🔍 Useful Commands

Run Docker

docker compose up

Stop Docker

docker compose down

Rebuild

docker compose up --build

View Logs

docker compose logs -f

Git Status

git status

Git Diff

git diff

---

🧪 Manual Testing Checklist

• Register organization
• Login
• Create room
• Create booking
• List bookings
• Booking detail
• Cancel booking
• Refresh token
• Logout
• Usage report
• Export CSV

---

📌 Notes

The API follows REST principles and returns JSON responses.

Validation errors use FastAPI's validation mechanism, while application-specific errors follow the documented error contract.

The project is designed to be deterministic and preserve the public API contract defined by the challenge specification.

Part 4 — Authentication, Authorization & API Documentation

🔐 Authentication

The API uses JSON Web Tokens (JWT) for stateless authentication.

Two token types are issued after a successful login:

Token	Purpose
Access Token	Authenticate API requests
Refresh Token	Obtain a new access token

The access token is supplied in the Authorization header:

Authorization: Bearer <access_token>

Every protected endpoint validates:

• Token signature
• Token expiration
• Token type
• Token revocation status
• Organization
• User role

---

🔄 Authentication Flow

Register

     │

     ▼

Login

     │

     ▼

Access Token
Refresh Token

     │

     ▼

Protected API

     │

     ▼

Logout

     │

     ▼

Access Token Revoked

     │

     ▼

Refresh Token

     │

     ▼

New Access Token

---

👤 Roles

Two roles exist within the platform.

Administrator

Administrators are allowed to

• Create rooms
• View organization reports
• Export booking data
• Access organization bookings
• View room statistics
• Cancel bookings inside their organization

---

Member

Members are allowed to

• Login
• View rooms
• Create bookings
• View their bookings
• Cancel their own bookings
• Check room availability

---

🔑 Token Lifecycle

Register

↓

Login

↓

Receive Tokens

↓

API Requests

↓

Logout

↓

Access Token Invalid

↓

Refresh

↓

New Access Token

Refresh tokens are single-use and cannot be reused after a successful refresh.

Access tokens become invalid immediately after logout.

---

🌐 API Endpoints

Authentication

Register

POST /auth/register

Request

{
  "org_name": "Acme",
  "username": "alice",
  "password": "password123"
}

Response

{
  "user_id": 1,
  "org_id": 1,
  "username": "alice",
  "role": "admin"
}

---

Login

POST /auth/login

Request

{
  "org_name": "Acme",
  "username": "alice",
  "password": "password123"
}

Response

{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "bearer"
}

---

Refresh Token

POST /auth/refresh

Request

{
  "refresh_token": "..."
}

Returns a fresh access token.

---

Logout

POST /auth/logout

Revokes the presented access token.

---

🏢 Rooms

List Rooms

GET /rooms

Returns every room belonging to the caller's organization.

---

Create Room

POST /rooms

Request

{
  "name": "Conference Room",
  "capacity": 12,
  "hourly_rate_cents": 2500
}

Validation:

• name must not be empty
• capacity > 0
• hourly_rate_cents > 0

---

Room Availability

GET /rooms/{room_id}/availability

Query Parameter

date=YYYY-MM-DD

Returns all confirmed busy intervals for the selected day.

---

Room Statistics

GET /rooms/{room_id}/stats

Response

{
  "room_id": 1,
  "total_confirmed_bookings": 15,
  "total_revenue_cents": 30000
}

---

📅 Bookings

Create Booking

POST /bookings

Request

{
  "room_id": 1,
  "start_time": "2026-07-10T10:00:00Z",
  "end_time": "2026-07-10T12:00:00Z"
}

Business rules enforced:

• Future booking only
• Whole-hour duration
• Duration between 1–8 hours
• No room conflicts
• User quota enforcement
• Rate limiting
• Price calculation
• Reference generation

---

List Bookings

GET /bookings?page=1&limit=10

Returns paginated bookings ordered by start time.

---

Booking Details

GET /bookings/{id}

Returns booking information together with refund history.

---

Cancel Booking

POST /bookings/{id}/cancel

Automatically computes refund based on cancellation timing.

Response

{
  "id": 1,
  "status": "cancelled",
  "refund_percent": 50,
  "refund_amount_cents": 1000
}

---

📊 Administration

Usage Report

GET /admin/usage-report

Provides room-wise booking and revenue statistics for a date range.

---

CSV Export

GET /admin/export

Supports:

• room filtering
• organization-wide export
• personal export

---

⚠ Error Codes

Code	Meaning
INVALID_CREDENTIALS	Login failed
ROOM_CONFLICT	Room already booked
QUOTA_EXCEEDED	User booking limit reached
RATE_LIMITED	Too many booking attempts
ROOM_NOT_FOUND	Room unavailable
BOOKING_NOT_FOUND	Booking unavailable
FORBIDDEN	Permission denied
ALREADY_CANCELLED	Booking already cancelled
INVALID_BOOKING_WINDOW	Invalid booking request
UNAUTHORIZED	Invalid or expired token

The API preserves a stable error contract across all endpoints to ensure predictable client behavior.

Part 5 — Business Rules & Design Decisions

📋 Business Rules

The implementation strictly follows the challenge specification and preserves the required API contract.

Booking Rules

• Bookings must start in the future.
• Booking duration must be between 1 and 8 hours.
• Only whole-hour bookings are allowed.
• Room conflicts are not permitted.
• Booking price is calculated automatically.
• Members may hold at most 3 active bookings within the quota window.
• Booking requests are rate limited.
• Every booking receives a unique reference code.

---

Refund Rules

Refund percentage depends on cancellation timing.

Time Before Start	Refund
≥ 24 Hours	100%
≥ 1 Hour	50%
< 1 Hour	0%

Each cancelled booking generates exactly one refund record.

---

Authorization Rules

Members can:

• Create bookings
• View their own bookings
• Cancel their own bookings

Administrators can:

• Create rooms
• View organization reports
• Export booking data
• Manage organization resources

---

Organization Isolation

Every request is scoped to the authenticated user's organization.

No endpoint exposes another organization's:

• Rooms
• Bookings
• Reports
• Statistics

---

🏛 Design Decisions

The implementation favors correctness and maintainability.

Key design principles include:

• Layered architecture
• Stateless authentication
• Explicit validation
• Clear separation of concerns
• Business logic isolated into services
• Predictable error handling
• Minimal API surface
• Thread-safe critical operations

---

⚡ Concurrency Strategy

Several endpoints modify shared resources.

To preserve business rules under concurrent requests, lightweight synchronization is used.

Protected operations include:

• Booking creation
• Booking cancellation
• User booking quota
• Booking reference generation

This prevents:

• Duplicate bookings
• Double refunds
• Quota races
• Duplicate reference codes

---

🧩 Error Handling

The API uses consistent JSON error responses.

Example:

{
  "detail": "Room already booked",
  "code": "ROOM_CONFLICT"
}

Framework validation errors follow FastAPI's standard response format.

---

📦 API Contract

The public API contract is preserved throughout development.

No changes were introduced to:

• Endpoint paths
• Request schemas
• Response schemas
• Status codes
• Error codes
• Authentication format

This ensures compatibility with automated black-box grading.

---