Busition API Server

Backend API server for the Busition platform, built with FastAPI and SQLAlchemy.

The service exposes versioned REST APIs for user authentication, shuttle schedule lookup, route and station management, organization join-code flows, and driver/passenger operations. The current codebase primarily targets the v1_5 API while still keeping several deprecated Firebase/DynamoDB-based endpoints for backward compatibility.

Overview

• Framework: FastAPI
• Language: Python
• ORM: SQLAlchemy
• Database: PostgreSQL
• Migration tool: Alembic
• Authentication: OAuth2 password flow with JWT
• External integrations:
  • Firebase Admin SDK
  • AWS DynamoDB (legacy endpoints)
  • Naver Maps Directions API

Key Features

• JWT-based authentication for Busition Console, Driver, Driver-for-Org, Mate, and docs access
• Versioned API delivery through fastapi-versioning
• Schedule lookup by platform and run-day management
• Route CRUD and route path generation via Naver Maps Directions API
• Station CRUD, bulk update, bulk delete, and station recreation
• Passenger manifest lookup for a specific route/station pair
• Organization join-code creation, lookup, deletion, and join flow
• Organization-scoped driver account management

Project Structure

.
├── app
│   ├── api
│   │   └── endpoints
│   ├── core
│   ├── db
│   ├── keyfile
│   ├── tests
│   └── main.py
├── alembic
├── nginx
├── Dockerfile
├── Jenkinsfile
└── requirements.txt

Important directories

• app/main.py: FastAPI application entry point
• app/api/api.py: top-level router registration
• app/api/endpoints/: versioned API modules
• app/core/: application settings and external service helpers
• app/db/: database session, models, and schemas
• app/tests/: test files
• alembic/: migration environment and revision history
• nginx/default.conf: reverse proxy example for api.busition.com

Requirements

• Python 3.11 recommended
• PostgreSQL database
• Additional local credentials for the current startup path:
  • Firebase Admin SDK service-account JSON
  • AWS credentials used by legacy DynamoDB-backed endpoints
  • Naver Cloud Platform Maps Directions API keys

Getting Started

1. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Create a local environment file:

cp app/.env.example app/.env

Set the following values in app/.env:

Variable	Required	Description
SQLALCHEMY_DATABASE_URL	Yes	PostgreSQL connection string used by SQLAlchemy
SECRET_KEY	Yes	JWT signing key
ALGORITHM	Yes	JWT algorithm, for example HS256
ACCESS_TOKEN_EXPIRE_MINUTES	Yes	Access token expiration time in minutes

4. Provide local key files

The current application imports some credential-backed modules during startup, so the following files should exist locally before you run the server:

• app/keyfile/aws_key.py
• app/keyfile/naver_api_key.py
• app/keyfile/busition-firebase-adminsdk-p6mxk-7c99130ac8.json

In other words, even if you do not plan to call every external-service endpoint, you may still need local placeholder or real credential files until the startup imports are refactored.

Run the Server

Local development

uvicorn app.main:app --reload

By default, Uvicorn serves the app on http://127.0.0.1:8000.

API documentation

• Swagger UI: http://127.0.0.1:8000/latest/docs
• ReDoc: http://127.0.0.1:8000/latest/redoc
• OpenAPI JSON: http://127.0.0.1:8000/latest/openapi.json

API Versioning

The project uses fastapi-versioning, so routes are exposed under versioned prefixes such as:

• v1_5
• v1_4
• v1_3
• v1_2
• v1_0

The latest docs endpoints are enabled for API exploration.

Main API Areas

Authentication and users

Base prefix: /users

• POST /latest/users/token: issue an access token
• GET /latest/users/me: return the current authenticated user
• GET /latest/users/type: list supported auth types
• POST /latest/users: sign up a new user
• POST /latest/users/driver-for-org: create an organization-only driver account
• GET /latest/users/email: check email availability

Schedules

Base prefix: /schedules

• Get schedules by platform: console, driver, mate-individual, mate-org
• Read, update, and delete run-day settings per route

Routes

Base prefix: /routes

• Get route geometry and station data
• Create routes
• Update routes
• Delete routes

Stations

Base prefix: /stations

• List stations for a route
• Create stations in bulk
• Update a single station
• Update stations in bulk
• Delete one or many stations
• Delete all stations for a route
• Recreate all stations for a route

Passengers

Base prefix: /passengers

• Get passenger manifests for a route/station pair

Organizations

Base prefix: /organizations

• Join an organization using a join code
• Create a join code
• Get the current join code
• Delete the current join code

Drivers

Base prefix: /drivers

• List all drivers in the current organization
• Separate organization-only driver accounts from unified Busition driver accounts
• Attach an existing Busition driver account to an organization

Deprecated Firebase endpoints

The repository still contains deprecated endpoints for legacy Firebase/DynamoDB workflows:

• /users-test
• /signup
• /signin

These remain in the codebase for backward compatibility and should not be treated as the primary API surface for new work.

Authentication Example

The API uses OAuth2 password flow. To get a token for the docs flow:

curl -X POST "http://127.0.0.1:8000/latest/users/token?busition_platform=docs" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=your-email@example.com&password=your-password"

Example response:

{
  "access_token": "your-jwt-token",
  "token_type": "bearer"
}

Use the returned bearer token in the Authorization header for protected endpoints.

Database and Migrations

SQLAlchemy models live in app/db/models.py, and Alembic configuration lives in alembic.ini and alembic/.

To apply migrations:

alembic upgrade head

To create a new migration:

alembic revision --autogenerate -m "describe your change"

Testing

Run the test suite with:

python3 -m pytest app/test_main.py app/tests

Some tests in this repository cover legacy API versions, so make sure your local database state and credentials are consistent with the code paths you want to exercise.

Docker

Build the image:

docker build -t busition-api-server .

Run the container:

docker run -d \
  --name busition-api-server \
  -p 8001:8001 \
  -e SQLALCHEMY_DATABASE_URL="postgresql://user:password@host:5432/dbname" \
  -e SECRET_KEY="replace-me" \
  -e ALGORITHM="HS256" \
  -e ACCESS_TOKEN_EXPIRE_MINUTES="10" \
  -v "$(pwd)/app/keyfile:/busition-api-server/app/keyfile" \
  --restart unless-stopped \
  busition-api-server

The container starts Uvicorn on port 8001.

Deployment Notes

• Jenkinsfile contains a Docker-based deployment pipeline
• nginx/default.conf shows an example reverse proxy configuration for api.busition.com
• The reverse proxy forwards traffic to the application running on localhost:8001

Operational Notes

• Route path generation currently depends on the Naver Maps Directions API and supports up to 15 waypoints in the present implementation
• Several legacy endpoints still rely on Firebase and DynamoDB
• The repository expects secrets and service credentials to be supplied locally or through deployment environment configuration
• Keep .env files and credential files out of version control in real deployments

License

This project is licensed under the GNU Affero General Public License v3.0 only (AGPL-3.0-only).