Imported from aps08/fullstack-clean-architecture (AGENTS.md). Install upstream with npx skills add aps08/fullstack-clean-architecture. Copyright stays with the author.

Agent & Project Guidelines

Welcome! This document provides commands, rules, and guidelines for developing and managing the Tempto project.

Agent Behavior Rules

These rules take highest priority and must be followed at all times.

1. Keep responses short — Always give the smallest response possible unless the user explicitly asks to describe in detail (e.g., "explain", "describe", "in detail").
2. No code changes on questions — If the user says "tell me", "how", asks a question with "?", or uses similar inquiry language, only answer — do not modify any code or files.
3. Explain differences with tables — Whenever explaining a difference or comparison between two or more things, always use a markdown table.

🚀 Quick Commands

Frontend (web/)

• Install: pnpm install
• Development Server: pnpm dev
• Production Build: pnpm build
• Preview Build: pnpm preview
• Linting: pnpm lint
• Lint & Fix: pnpm lint:fix
• Formatting: pnpm format
• Format Check: pnpm format:check
• Unit Testing (watch): pnpm test
• Unit Testing (UI): pnpm test:ui
• Unit Testing (coverage): pnpm test:cov
• E2E Testing: pnpm test:e2e

Backend (server/)

• Environment Sync: uv sync
• Development Server: uv run task dev
• Run Linter: uv run task check
• Run Formatter: uv run task format
• Type Checking: uv run task type-check
• Database Migrations:
  • Upgrade: uv run task upgrade (runs alembic upgrade head)
  • Downgrade: uv run task downgrade (runs alembic downgrade -1)
• Testing: uv run task test
• Generate Coverage HTML Report: uv run task cov-html (runs pytest --cov=app --cov-report=html)

Backend Folder Structure (server/)

The application resides in the server/app/ directory:

• core/: Core configurations, containers (dependency injection), DB connectors, standard middleware, unified exceptions, logging, security, and global dependencies.

• models/: Declarative SQLAlchemy models (subclassing BaseModel).

• repositories/: Repositories handling database data access (inheriting from BaseRepository).

• schemas/: Pydantic request/response validation schemas (inheriting from BaseModel / using to_camel and populate_by_name).

• services/: Service classes implementing business logic (inheriting from BaseService).

• routes/: API routers and controllers organized by version:

  • v1/: Auth endpoints (routes.py, endpoints/auth.py).
  • v2/: Resource-oriented REST APIs (routes.py, endpoints/todos.py, endpoints/attachments.py, endpoints/users.py).

• utils/: Core utilities and helpers.

Frontend Folder Structure (web/)

The source code resides in the web/src/ directory:

• components/: Reusable component library. Shared/atomic inputs are placed in common/ (e.g. Button.tsx, Input.tsx, Modal.tsx).

• constants/: Shared UI and navigation configuration constants.

• features/: Modular components implementing feature-specific pages (e.g., todo/TodoList.tsx, todo/TodoEdit.tsx, Archives.tsx, Attachments.tsx).

• hooks/: React state and fetching hooks:

  • queries/: React Query hooks for fetching data (e.g., todos.ts).
  • mutations/: React Query mutations for sending data (e.g., auth.ts, todos.ts).
  • shared/: Generic frontend helpers (e.g., useDebounce.ts).

• lib/: Client utilities such as the API axios client.ts and query configuration query.ts.

• models/: Client-side Zod validation schemas and types (e.g., todo.ts, attachment.ts).

• routes/: File-based TanStack Router configuration directories (e.g., _authenticated/, _guest/).

• store/: Client-side state stores (e.g. auth.store.ts).

• utils/: Formatting and processing helper functions (e.g. helper.ts).

Backend Technology Stack

• FastAPI (Async) for the API layer.
• SQLAlchemy 2.0 (Async) with asyncpg for database connection and ORM.
• Dependency Injector for IoC container management.
• Alembic for schema migrations.
• Clean Architecture Principles: Keep business logic separated (Routes -> Services -> Repositories -> Models).

Frontend Technology Stack

• React 19 (TypeScript) built with Vite 8.
• React Compiler (babel-plugin-react-compiler): Memoization is automatic. Avoid manual useMemo and useCallback unless necessary.
• TanStack Router: File-based routing with automatic code-splitting enabled in vite.config.ts.
• TanStack Query & Form: Server state caching and type-safe form validations.
• Zod: Validation schemas aligned with backend Pydantic models.

📖 Coding & Design Guidelines

Frontend

1. Routing & Code Splitting:
   • Keep page-specific components inside the web/src/features/ directory.
   • Map them to files in web/src/routes/ using static route configurations. The build pipeline handles code splitting automatically.
2. Search Components:
   • When searching within a paginated view, always reset the current page parameter to 1 on query changes (setPage(1)) to avoid out-of-bounds pagination matches.
3. MIME Types vs. Filenames:
   • Always resolve visual elements (like file type icons via getAttachmentIcon(filename)) using the actual file name/extension rather than the MIME type string.
4. For writing test for frontend check the react testing skill.

Backend

1. Async Flow: Always use async/await for database actions, API calls, and handlers.
2. Rate Limiting: Apply @rate_limit decorators to API endpoints according to resource utilization profiles.
3. UTC Datetimes: Always save and process times using timezone-aware UTC format.
4. Background Tasks: Use BackgroundTasks when sending emails or other long-running tasks to prevent user delays in response to user requests.
5. For writing test for backend check the python testing skill.

STRICTLY FOLLOW THESE RULES

1. Run uv run task check, uv run task format and uv run task type-check if more than 5 *.py files in the backend (server/app) codebase have been changed in the current session.
2. Run uv run task cov-html or uv run task test if changes have been made to *.py files in the backend (server/) codebase inside the tests directory.
3. Run pnpm lint, pnpm lint:fix, pnpm format and pnpm format:check if more than 10 *.ts or *.tsx files in web/src/ have been changed in the current session.
4. Run pnpm test or pnpm test:cov if changes have been made to files in the web/tests/ directory and more than 5 files have changed in the current session.
5. Always update docs/API_FLOW.md when making changes to the backend API using the documentation skills.
6. Always update docs/DATA_MODEL.md when making changes to the database schema using the documentation skills.