# SIBU Project Rules and Conventions

## Project Structure

This is a full-stack transportation application:
- **Backend**: FastAPI + SQLModel + Postgres (in `backend/` folder) using uv
- **Frontend**: Vue3 + Vite + Shadcn (in `frontend/` folder) using Bun

## Package Management

### Backend
- **Always use `uv` for package management**
- **NEVER edit `pyproject.toml` manually** - use `uv add <package>` instead
- Execute backend with: `uv run fastapi dev app/main.py` (development) or `uv run fastapi run app/main.py` (production)
- Run migrations with: `uv run alembic upgrade head`

### Frontend
- **Always use `bun` for package management**
- **NEVER edit `package.json` manually** - use `bun add <package>` instead
- Run development server: `bun run dev`
- Build for production: `bun run build`

## Backend Conventions

### Configuration
- Use `pydantic-settings` BaseSettings class in `app/core/config.py` for all environment variable management
- Environment files: `.env.development` and `.env.production`
- Database URL format: `postgresql+asyncpg://localhost:5432/sibu_dev`

### Code Style
- Use Python type hints for all function parameters and return types
- Use SQLModel for database models
- Use Pydantic schemas for request/response validation
- Follow FastAPI best practices for API routes
- Use dependency injection for database sessions

### Project Structure
```
backend/
  ├── app/
  │   ├── api/          # API route handlers
  │   ├── core/         # Configuration and database
  │   ├── models/       # SQLModel models
  │   ├── schemas/      # Pydantic schemas
  │   └── services/     # Business logic
  ├── alembic/          # Database migrations
  └── pyproject.toml    # Managed by uv
```

## Frontend Conventions

### Code Style
- Use Vue3 Composition API with `<script setup>`
- Use TypeScript for type safety
- Use Pinia for state management
- Use Vue Router for navigation
- Import paths should use `@/` alias for `src/` directory

### Project Structure
```
frontend/
  src/
    ├── components/     # Reusable Vue components
    ├── views/         # Main screen components
    ├── services/      # API client services
    ├── stores/        # Pinia stores
    ├── types/         # TypeScript type definitions
    ├── composables/   # Vue composables
    ├── utils/         # Helper functions
    └── router/        # Vue Router configuration
```

### Environment Variables
- Frontend env files: `.env.development` and `.env.production`
- All env vars must be prefixed with `VITE_` to be accessible in the app
- Default API URL for development: `http://localhost:8000`
- API URL will change for production

## Google Maps Integration

- Use Google Maps JavaScript API (development mode initially)
- API key should be stored in `.env` files
- Use `@googlemaps/js-api-loader` package for loading the API

## Database

- Use PostgreSQL with asyncpg driver
- Use SQLModel for ORM (combines SQLAlchemy + Pydantic)
- Use Alembic for migrations
- Database connection managed through `app/core/database.py`

## API Design

- RESTful API endpoints
- Use `/api/` prefix for all API routes
- Response models using Pydantic schemas
- Proper error handling and HTTP status codes

## General Guidelines

- Always use environment variables for configuration
- Never commit `.env` files (use `.env.example` as template)
- Use TypeScript/Python type hints for better code quality
- Follow the service layer pattern for business logic
- Use composables for reusable Vue logic
- Keep components small and focused
- Write clear, descriptive commit messages

## Testing

- Backend: Use FastAPI's TestClient for API testing
- Frontend: Use Vue Test Utils for component testing
- Always test critical paths before deploying