Initial commit: SIBU 2.0 MISSION

2026-02-21 09:53:31 -05:00
commit 0c7aa53c8b
400 changed files with 67708 additions and 0 deletions
--- a/.cursor/rules/main.mdc
+++ b/.cursor/rules/main.mdc
@ -0,0 +1,113 @@
+# 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