Peso SaaS Monorepo Development
Expert development rules for a full-stack SaaS monorepo with FastAPI backend, Vue.js frontend, React Native mobile app, and AWS infrastructure.
Architecture Overview
You are working with a monorepo structure containing:
`backend/` - FastAPI Python application`frontend/` - Vue.js 3 application`mobile-app/` - React Native/Ionic application`infra/` - Docker, Terraform, and infrastructure codeEach module must be autonomous with its own dependencies. Use relative imports between modules and maintain strict separation of concerns.
Naming Conventions
Follow these naming rules strictly:
**Python files**: snake_case (`user_service.py`, `weight_entry.py`)**JavaScript/Vue files**: camelCase or PascalCase (`userService.js`, `WeightEntry.vue`)**Folders**: kebab-case (`mobile-app/`, `weight-entries/`)**Modal components**: Always in `components/Modal/` directory (`EditWeightEntryModal.vue`)**Python variables**: snake_case**JavaScript variables**: camelCase**Constants**: UPPER_SNAKE_CASE**Classes**: PascalCase in all languagesBackend (FastAPI/Python) Rules
Import Order
Always organize imports in this order:
1. Standard library imports
2. Third-party packages
3. Local imports
SQLAlchemy Models
Always inherit from `Base`Add indexes on frequently searched fieldsDefine `nullable=False` for required fieldsUse meaningful `__tablename__` valuesPydantic Schemas
Create separate schemas for:
`Create` - for creation requests`Update` - all fields Optional`Response` - for API responses with `class Config: from_attributes = True`Services Pattern
Keep business logic in service classes, not routesServices accept database session in `__init__`Services handle validation and business rulesAPI Routes
Use consistent prefixes: `/api/v1/{resource}`Include `tags` for API documentationUse appropriate status codes (201 for creation, 404 for not found)Use dependencies for authentication (`Depends(get_current_user)`)Error Handling
Use `HTTPException` with appropriate status codesProvide meaningful error messagesUse helper functions like `get_user_or_404`Testing
Use pytest with fixturesFollow Arrange-Act-Assert patternUse `TestClient` for API testsCreate separate test classes for each resourceMigrations
Always create Alembic migrations for schema changesUse descriptive migration namesNever manually edit the database schemaFrontend (Vue.js) Rules
Component Structure
Always organize Single File Components in this order:
1. `<template>` - template first
2. `<script>` - use Composition API
3. `<style scoped>` - scoped styles last
Composition API
Use `setup()` functionImport `ref`, `computed`, `onMounted` from VueReturn all reactive data and methodsPinia Stores
Use `defineStore` with Composition API styleOrganize as: state (ref), getters (computed), actions (functions)Handle loading states and errorsAPI Services
Centralize all API calls in service modulesCreate axios instance with baseURL from environmentAdd interceptors for authentication tokensExport resource-specific API objectsRouter Configuration
Use lazy loading for route componentsDefine `meta` fields for authentication requirementsImplement navigation guards for auth protectionComponent Props
Always validate props with type and validatorProvide default valuesDocument all emitted events with `emits` optionModal Components
Place all modals in `components/Modal/` directoryStandard structure: header with title and close button, body, action buttonsEmit `close` and `submit` eventsAccept `isVisible` propStyling
Use Tailwind CSS utility classesKeep custom CSS scopedUse semantic class namesMobile (React Native) Rules
Component Structure
Use functional components with hooksExtract complex logic into custom hooksDefine StyleSheet at component bottomCustom Hooks
Prefix with `use` (e.g., `useUser`)Return object with data, loading state, error, and refetch functionHandle cleanup in useEffectNavigation
Use React NavigationConfigure stack navigator with typed routesHide headers when needed with optionsLocal Storage
Use AsyncStorage for persistent dataCreate wrapper module with semantic methodsAlways await async storage operationsInfrastructure (Docker/AWS) Rules
Dockerfiles
Use multi-stage builds to optimize image sizeStart with minimal base images (alpine)Copy package files before source codeRun production builds in separate stageDocker Compose
Define health checks for all servicesUse `depends_on` with `condition: service_healthy`Organize environment variables clearlyUse volume mounts for developmentEnvironment Variables
Prefix with service nameProvide secure default valuesNever commit secrets to version controlDocument all required variablesTerraform
Use reusable modulesTag all resources with Name, Environment, ProjectUse variables for configurable valuesMaintain separate environments (dev, staging, production)Testing Standards
Backend Tests (Pytest)
Use fixtures for test data and clientsCreate database fixtures that handle setup/teardownTest happy paths and error casesMock external dependenciesFrontend Tests (Vitest)
Use `@vue/test-utils` for component testingMount components with required propsTest user interactions and emitted eventsMock API calls and storesSecurity Requirements
Authentication
Use JWT tokens with expirationImplement refresh token mechanismValidate tokens server-sideAlways use HTTPS in productionData Validation
Validate all user inputUse Pydantic for backend validationSanitize data before storageUse ORM parameterized queries to prevent SQL injectionSecrets Management
Never commit secrets to codeUse environment variablesHash passwords with bcryptUse secrets managers in productionDocumentation Standards
Write all comments in EnglishDocument all public functions with docstringsMaintain README.md in each directoryUse emojis for visual clarity in documentationKey Principles
1. **Autonomy**: Each module must be self-contained
2. **Consistency**: Follow naming and structure conventions strictly
3. **Security**: Validate input, protect secrets, use HTTPS
4. **Testing**: Write tests for all business logic
5. **Documentation**: Keep docs current and clear
6. **Simplicity**: Avoid over-engineering, keep solutions focused
When implementing features:
1. Start with data models and schemas
2. Create service layer for business logic
3. Implement API routes/endpoints
4. Build UI components
5. Add tests at each layer
6. Update documentation
Always separate concerns, validate input, handle errors gracefully, and maintain consistency across the monorepo.