Development Standards

Python 3.12+ TypeScript Strict Ruff & Mypy Conventional Commits

To keep the CloudRader ecosystem consistent, robust, and maintainable across all independent services, every repository adheres to these core engineering standards and development conventions.

Standards Overview Matrix

Backend Standards (Python)

All Python services within CloudRader follow modern, asynchronous Python development standards:

1. Runtime & Package Management

• Python Version: Python 3.12+ (pinned per repository in pyproject.toml).
• Package Manager: Use uv as the single tool for dependency resolution, virtual environment management, and lockfile maintenance (uv.lock).
• Dependencies: Group development and testing dependencies separately under [dependency-groups] in pyproject.toml.

2. Framework & Architecture

• Framework: FastAPI for declarative REST APIs with automatic OpenAPI 3.0 schema generation.
• Layered Architecture: Decouple domain models, database repositories, application services, and HTTP route handlers.
• Data Validation: Pydantic v2 for data models, request parsing, and environment configuration (pydantic-settings).

3. Persistence & Database Migrations

• ORM: SQLAlchemy 2.0 using asynchronous sessions (AsyncSession) and drivers (asyncpg for PostgreSQL).
• Migrations: Database schema evolution must be managed via explicit, versioned Alembic migration scripts.
• Data Isolation: Services manage their own independent database schemas; cross-database joins and shared tables are prohibited.

4. Code Quality & Type Safety

• Linter & Formatter: Ruff handles all linting and formatting in a single pass.
• Type Checking: Full static type hints are required on all function signatures, methods, and variables using mypy.

Frontend Standards (Web UI)

CloudRader user interfaces are designed to be fast, responsive, and accessible across mobile and desktop browsers:

1. Language & Typing

• TypeScript: Strict mode enabled ("strict": true). Avoid any types; define explicit interfaces and generic types in dedicated type definitions.
• Build Tooling: Vite with modern ECMAScript target modules for fast development and lightweight production bundles.

2. Component Architecture & State

• React: Functional components with hooks. Keep UI components focused on presentation.
• Data Fetching: Use TanStack Query (React Query) or typed Axios client modules for server state, background caching, and optimistic updates.
• Separation of Concerns: Never embed direct raw network calls inside rendering components.

3. Styling & Responsive Design

• Tailwind CSS: Utility-first CSS framework for clean, maintainable styling.
• Mobile First: All layouts must be responsive, adapting smoothly to mobile viewports (< 768px) with slide-over drawers, touch targets, and horizontal table scrolling.
• Theme Support: Design components to respect both light and dark color schemes cleanly.

Documentation Standards

Documentation in CloudRader is treated as a first-class product artifact:

• Engine: Author documentation in Markdown rendered by Zensical.
• Structure: Exactly one H1 (#) per page, followed by logical H2 (##) and H3 (###) hierarchy.
• Icons & Badges: Use Zensical icon shortcodes (:material-...:, :fontawesome-...:) and CSS badge classes. Do not use raw emoji in headings.
• Fenced Blocks: Always specify code language tags (bash, python, typescript, yaml, mermaid) for syntax highlighting.
• Typography: Use backticks for commands, filenames, paths, and literal values. Use ASCII for new text.
• Relative Links: Verify all cross-references and internal links resolve correctly.

Commit Message Conventions

We adhere to the Conventional Commits specification across all repositories:

<type>(<scope>): <subject>

[optional body]

[optional footer(s)]

Commit Types