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 code

Each 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 languages

Backend (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 fields

Define `nullable=False` for required fields

Use meaningful `__tablename__` values

Pydantic 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 routes

Services accept database session in `__init__`

Services handle validation and business rules

API Routes

Use consistent prefixes: `/api/v1/{resource}`

Include `tags` for API documentation

Use 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 codes

Provide meaningful error messages

Use helper functions like `get_user_or_404`

Testing

Use pytest with fixtures

Follow Arrange-Act-Assert pattern

Use `TestClient` for API tests

Create separate test classes for each resource

Migrations

Always create Alembic migrations for schema changes

Use descriptive migration names

Never manually edit the database schema

Frontend (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()` function

Import `ref`, `computed`, `onMounted` from Vue

Return all reactive data and methods

Pinia Stores

Use `defineStore` with Composition API style

Organize as: state (ref), getters (computed), actions (functions)

Handle loading states and errors

API Services

Centralize all API calls in service modules

Create axios instance with baseURL from environment

Add interceptors for authentication tokens

Export resource-specific API objects

Router Configuration

Use lazy loading for route components

Define `meta` fields for authentication requirements

Implement navigation guards for auth protection

Component Props

Always validate props with type and validator

Provide default values

Document all emitted events with `emits` option

Modal Components

Place all modals in `components/Modal/` directory

Standard structure: header with title and close button, body, action buttons

Emit `close` and `submit` events

Accept `isVisible` prop

Styling

Use Tailwind CSS utility classes

Keep custom CSS scoped

Use semantic class names

Mobile (React Native) Rules

Component Structure

Use functional components with hooks

Extract complex logic into custom hooks

Define StyleSheet at component bottom

Custom Hooks

Prefix with `use` (e.g., `useUser`)

Return object with data, loading state, error, and refetch function

Handle cleanup in useEffect

Navigation

Use React Navigation

Configure stack navigator with typed routes

Hide headers when needed with options

Local Storage

Use AsyncStorage for persistent data

Create wrapper module with semantic methods

Always await async storage operations

Infrastructure (Docker/AWS) Rules

Dockerfiles

Use multi-stage builds to optimize image size

Start with minimal base images (alpine)

Copy package files before source code

Run production builds in separate stage

Docker Compose

Define health checks for all services

Use `depends_on` with `condition: service_healthy`

Organize environment variables clearly

Use volume mounts for development

Environment Variables

Prefix with service name

Provide secure default values

Never commit secrets to version control

Document all required variables

Terraform

Use reusable modules

Tag all resources with Name, Environment, Project

Use variables for configurable values

Maintain separate environments (dev, staging, production)

Testing Standards

Backend Tests (Pytest)

Use fixtures for test data and clients

Create database fixtures that handle setup/teardown

Test happy paths and error cases

Mock external dependencies

Frontend Tests (Vitest)

Use `@vue/test-utils` for component testing

Mount components with required props

Test user interactions and emitted events

Mock API calls and stores

Security Requirements

Authentication

Use JWT tokens with expiration

Implement refresh token mechanism

Validate tokens server-side

Always use HTTPS in production

Data Validation

Validate all user input

Use Pydantic for backend validation

Sanitize data before storage

Use ORM parameterized queries to prevent SQL injection

Secrets Management

Never commit secrets to code

Use environment variables

Hash passwords with bcrypt

Use secrets managers in production

Documentation Standards

Write all comments in English

Document all public functions with docstrings

Maintain README.md in each directory

Use emojis for visual clarity in documentation

Key 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.

Peso SaaS Monorepo Development

Safety Concern

Peso SaaS Monorepo Development

Architecture Overview

Naming Conventions

Backend (FastAPI/Python) Rules

Import Order

SQLAlchemy Models

Pydantic Schemas

Services Pattern

API Routes

Error Handling

Testing

Migrations

Frontend (Vue.js) Rules

Component Structure

Composition API

Pinia Stores

API Services

Router Configuration

Component Props

Modal Components

Styling

Mobile (React Native) Rules

Component Structure

Custom Hooks

Navigation

Local Storage

Infrastructure (Docker/AWS) Rules

Dockerfiles

Docker Compose

Environment Variables

Terraform

Testing Standards

Backend Tests (Pytest)

Frontend Tests (Vitest)

Security Requirements

Authentication

Data Validation

Secrets Management

Documentation Standards

Key Principles

Reviews (0)