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:
```bash
make setup
```

2. Set up environment variables:
```bash
# 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:
```bash
make migrate-up
```

4. Run both backend and frontend:
```bash
make dev
```

Or run them separately:
```bash
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:
```bash
cd backend
```

2. Install dependencies:
```bash
uv sync
```

3. Set up environment variables:
```bash
# Copy and edit .env.development
cp .env.example .env.development
# Edit .env.development with your database URL
```

4. Run database migrations:
```bash
uv run alembic upgrade head
```

5. Start the development server:
```bash
uv run fastapi dev app/main.py
```

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

#### Frontend Setup

1. Navigate to frontend directory:
```bash
cd frontend
```

2. Install dependencies:
```bash
bun install
```

3. Set up environment variables:
```bash
# 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:
```bash
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]