SIB/README.md

SIBU - Sistema de Transporte

A full-stack public transportation application for tracking bus routes, schedules, and providing transportation services information.

Project Structure

sibu/
├── backend/          # FastAPI backend (uv)
├── frontend/         # Vue3 frontend (Bun)
├── old/             # Archived Flutter app
└── .cursor/         # Cursor IDE rules

Tech Stack

Backend

• FastAPI - Modern Python web framework
• SQLModel - SQL database ORM (combines SQLAlchemy + Pydantic)
• PostgreSQL - Database
• uv - Fast Python package manager
• Alembic - Database migrations

Frontend

• Vue 3 - Progressive JavaScript framework
• Vite - Fast build tool
• TypeScript - Type-safe JavaScript
• Pinia - State management
• Vue Router - Client-side routing
• Bun - Fast JavaScript runtime and package manager
• Google Maps API - Map integration

Getting Started

Prerequisites

• Python 3.13+ (for backend)
• uv (Python package manager)
• Node.js 18+ or Bun (for frontend)
• PostgreSQL database
• Make (for using Makefile commands)

Quick Start with Makefile

The easiest way to get started is using the provided Makefile:

1. Install all dependencies:

make setup

2. Set up environment variables:

# Backend: Copy and edit .env.development
cd backend && cp .env.example .env.development
# Edit backend/.env.development with your database URL

# Frontend: Copy and edit .env.development
cd frontend && cp .env.example .env.development
# Edit frontend/.env.development with your API URL and Google Maps key

3. Apply database migrations:

make migrate-up

4. Run both backend and frontend:

make dev

Or run them separately:

make dev-backend   # Backend only (http://localhost:8000)
make dev-frontend  # Frontend only (http://localhost:5173)

Manual Setup

Backend Setup

1. Navigate to backend directory:

cd backend

2. Install dependencies:

uv sync

3. Set up environment variables:

# Copy and edit .env.development
cp .env.example .env.development
# Edit .env.development with your database URL

4. Run database migrations:

uv run alembic upgrade head

5. Start the development server:

uv run fastapi dev app/main.py

The API will be available at http://localhost:8000

Frontend Setup

1. Navigate to frontend directory:

cd frontend

2. Install dependencies:

bun install

3. Set up environment variables:

# Copy and edit .env.development
cp .env.example .env.development
# Edit .env.development with your API URL and Google Maps key

4. Start the development server:

bun run dev

The app will be available at http://localhost:5173

Environment Variables

Backend (.env.development)

DATABASE_URL=postgresql+asyncpg://localhost:5432/sibu_dev
ENVIRONMENT=development
DEBUG=true

Frontend (.env.development)

VITE_API_URL=http://localhost:8000
VITE_GOOGLE_MAPS_API_KEY=your-google-maps-api-key-here

API Endpoints

• GET /api/routes - Get all routes
• GET /api/routes/{id} - Get route by ID
• GET /api/routes/{id}/stops - Get stops for a route
• GET /api/bus-stops - Get all bus stops
• GET /api/bus-stops/{id} - Get bus stop by ID
• GET /api/bus-stops/{id}/routes - Get routes for a bus stop
• GET /api/schedules - Get schedules (query params: route_id, stop_id)
• GET /api/coupons - Get coupons
• GET /api/taxis - Get taxis

Development

Makefile Commands

The project includes a Makefile with convenient commands:

Installation:

• make install - Install all dependencies
• make install-backend - Install backend dependencies only
• make install-frontend - Install frontend dependencies only
• make setup - Full setup (install + instructions)

Development:

• make dev - Run both backend and frontend concurrently
• make dev-backend - Run backend development server
• make dev-frontend - Run frontend development server

Migrations:

• make migrate-up - Apply all pending migrations
• make migrate-down - Rollback last migration
• make migrate-create NAME=migration_name - Create a new migration
• make migrate-history - Show migration history
• make migrate-current - Show current migration version

Building:

• make build - Build both backend and frontend
• make build-backend - Build backend only
• make build-frontend - Build frontend only

Other:

• make clean - Clean all build artifacts
• make test - Run all tests
• make help - Show all available commands

Manual Commands

Backend Commands

• uv add <package> - Add a dependency
• uv run fastapi dev app/main.py - Run development server
• uv run fastapi run app/main.py - Run production server
• uv run alembic upgrade head - Run database migrations
• uv run alembic revision --autogenerate -m "name" - Create migration

Frontend Commands

• bun add <package> - Add a dependency
• bun run dev - Run development server
• bun run build - Build for production

Project Conventions

See .cursor/rules/main.mdc for detailed coding conventions and best practices.

License

[Your License Here]