114 lines
3.7 KiB
Plaintext
114 lines
3.7 KiB
Plaintext
# 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
|