rpr-cli 0.1.1__py3-none-any.whl

rpr/map/walker.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import pathspec
+
+type Language = Literal["python", "typescript", "javascript", "rust", "cpp"]
+
+_EXT_TO_LANG: dict[str, Language] = {
+    ".py": "python",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".rs": "rust",
+    ".cpp": "cpp",
+    ".cc": "cpp",
+    ".cxx": "cpp",
+    ".c": "cpp",
+    ".h": "cpp",
+    ".hpp": "cpp",
+    ".hxx": "cpp",
+}
+
+_IGNORED_DIRS: frozenset[str] = frozenset(
+    {
+        ".venv",
+        "venv",
+        ".env",
+        "node_modules",
+        "__pycache__",
+        "dist",
+        "build",
+        ".nx",
+        "target",
+        ".git",
+        "vendor",
+    }
+)
+
+
+def _load_gitignore(root: Path) -> pathspec.PathSpec | None:
+    """Load .gitignore patterns from root; returns None if file absent."""
+    gitignore = root / ".gitignore"
+    if not gitignore.is_file():
+        return None
+    lines = gitignore.read_text(encoding="utf-8", errors="replace").splitlines()
+    return pathspec.PathSpec.from_lines("gitignore", lines)
+
+
+@dataclass
+class SourceFile:
+    abs_path: Path
+    rel_path: Path
+    language: Language
+
+
+@dataclass
+class ProjectEntry:
+    abs_path: Path
+    rel_path: Path
+    is_dir: bool
+
+
+def walk(root: Path) -> list[SourceFile]:
+    spec = _load_gitignore(root)
+    results: list[SourceFile] = []
+    _recurse(root, root, results, spec)
+    return results
+
+
+def list_project_entries(root: Path) -> list[ProjectEntry]:
+    spec = _load_gitignore(root)
+    results: list[ProjectEntry] = []
+    _recurse_entries(root, root, results, spec)
+    return results
+
+
+def _recurse(
+    root: Path,
+    current: Path,
+    results: list[SourceFile],
+    spec: pathspec.PathSpec | None,
+) -> None:
+    try:
+        entries = list(current.iterdir())
+    except PermissionError:
+        return
+    for entry in entries:
+        if entry.is_symlink():
+            continue
+        rel = entry.relative_to(root)
+        if entry.is_dir():
+            if entry.name in _IGNORED_DIRS:
+                continue
+            # Append "/" so pathspec matches directory-only patterns (e.g. "secret/")
+            if spec is not None and spec.match_file(str(rel) + "/"):
+                continue
+            _recurse(root, entry, results, spec)
+        elif entry.is_file():
+            if spec is not None and spec.match_file(str(rel)):
+                continue
+            lang = _EXT_TO_LANG.get(entry.suffix)
+            if lang is not None:
+                results.append(
+                    SourceFile(
+                        abs_path=entry.resolve(),
+                        rel_path=rel,
+                        language=lang,
+                    )
+                )
+
+
+def _recurse_entries(
+    root: Path,
+    current: Path,
+    results: list[ProjectEntry],
+    spec: pathspec.PathSpec | None,
+) -> None:
+    try:
+        entries = sorted(
+            current.iterdir(),
+            key=lambda entry: (not entry.is_dir(), entry.name.lower()),
+        )
+    except PermissionError:
+        return
+
+    for entry in entries:
+        if entry.is_symlink():
+            continue
+        rel = entry.relative_to(root)
+        if entry.is_dir():
+            if entry.name in _IGNORED_DIRS:
+                continue
+            if spec is not None and spec.match_file(str(rel) + "/"):
+                continue
+            results.append(
+                ProjectEntry(abs_path=entry.resolve(), rel_path=rel, is_dir=True)
+            )
+            _recurse_entries(root, entry, results, spec)
+            continue
+
+        if spec is not None and spec.match_file(str(rel)):
+            continue
+        results.append(
+            ProjectEntry(abs_path=entry.resolve(), rel_path=rel, is_dir=False)
+        )

rpr/scaffolds/domain/base_entity.md

@@ -0,0 +1,30 @@
+Reference scaffold for the shared SQLModel base entity.
+
+Uses SQLAlchemy server-side defaults so that `id`, `created_at`, and `updated_at`
+are generated by the database rather than the Python runtime.
+
+```python
+from datetime import datetime
+
+from sqlalchemy import DateTime, String, func
+from sqlmodel import Field, SQLModel
+
+
+class BaseEntity(SQLModel):
+    id: str = Field(
+        default=None,
+        primary_key=True,
+        sa_type=String(36),
+        sa_column_kwargs={"server_default": func.gen_random_uuid()},
+    )
+    created_at: datetime = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={"server_default": func.now()},
+    )
+    updated_at: datetime = Field(
+        default=None,
+        sa_type=DateTime(timezone=True),
+        sa_column_kwargs={"server_default": func.now(), "onupdate": func.now()},
+    )
+```

rpr/scaffolds/domain/base_repo.md

@@ -0,0 +1,48 @@
+Reference scaffold for the shared async base repository.
+
+Uses `AsyncSession` from `sqlmodel.ext.asyncio.session` and the `@mapper`
+decorator from `utils/mapper_util` to handle DTO conversion transparently.
+Replace `your_app_domain` with the actual package name during code generation.
+
+```python
+from abc import ABC
+from collections.abc import Callable
+from typing import Generic, TypeVar
+
+from sqlalchemy.ext.asyncio import AsyncEngine
+from sqlmodel import SQLModel, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from your_app_domain.utils.mapper_util import mapper
+
+ModelType = TypeVar("ModelType", bound=SQLModel)
+
+
+class BaseRepository(Generic[ModelType], ABC):
+    def __init__(
+        self,
+        model: type[ModelType],
+        engine: AsyncEngine,
+        dto_func: Callable,
+    ):
+        self.model = model
+        self.engine = engine
+        self.dto_func = dto_func
+
+    @mapper
+    async def get_by_id(self, id: str) -> ModelType | None:
+        async with AsyncSession(self.engine) as session:
+            statement = select(self.model).where(self.model.id == id)
+            result = await session.exec(statement)
+            return result.first()
+
+    @mapper
+    async def create(self, obj_in: ModelType) -> ModelType:
+        async with AsyncSession(self.engine) as session:
+            obj_data = obj_in.model_dump()
+            db_obj = self.model(**obj_data)
+            session.add(db_obj)
+            await session.commit()
+            await session.refresh(db_obj)
+            return db_obj
+```

rpr/scaffolds/domain/container.md

@@ -0,0 +1,76 @@
+## Domain Container Template
+
+Target path: `packages/python/domain/src/{name_underscore}_domain/config/container.py`
+
+Use this template when scaffolding the domain DI container. It wires the core infrastructure providers — database engine and HTTP client — as singletons driven by `Settings`.
+
+The first Python block is the generated file used by `rpr generate domain` and `rpr add template domain_container`.
+
+```python
+from __future__ import annotations
+
+import httpx
+from dependency_injector import containers, providers
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from your_app_domain.config.settings import Settings
+
+
+class Container(containers.DeclarativeContainer):
+    wiring_config = containers.WiringConfiguration(modules=[])
+
+    config = providers.Singleton(Settings)
+
+    db_engine = providers.Singleton(
+        lambda settings: create_async_engine(
+            settings.database_url,
+            echo=settings.db_echo,
+            pool_pre_ping=True,
+            pool_recycle=3600,
+        ),
+        settings=config,
+    )
+
+    http_client = providers.Singleton(
+        httpx.AsyncClient,
+        timeout=config.provided.http_timeout,
+        limits=providers.Factory(
+            httpx.Limits,
+            max_connections=config.provided.httpx_max_connections,
+            max_keepalive_connections=config.provided.http_max_keepalive,
+        ),
+    )
+
+    # To add lifecycle methods (startup/shutdown hooks), override __new__:
+    #
+    #   def __new__(cls):
+    #       instance = super().__new__(cls)
+    #       return add_lifecycle_methods(instance)
+    #
+    # Implement add_lifecycle_methods() in this module to attach
+    # startup and shutdown handlers to the container instance.
+```
+
+## What This Template Provides
+
+- `config`: a singleton `Settings` instance that reads from `.env`.
+- `db_engine`: a singleton async SQLAlchemy engine built from `settings.database_url`, with connection-pool tuning defaults (`pool_pre_ping`, `pool_recycle`).
+- `http_client`: a singleton `httpx.AsyncClient` with timeout and connection limits sourced from `Settings`.
+
+## Lifecycle Extension Pattern
+
+If the project needs startup or shutdown hooks (e.g., acquiring a connection pool, registering signal handlers), override `__new__` on `Container`:
+
+```python
+def __new__(cls):
+    instance = super().__new__(cls)
+    return add_lifecycle_methods(instance)
+```
+
+Define `add_lifecycle_methods(instance)` in the same module to attach `on_startup` and `on_shutdown` handlers without modifying the provider declarations.
+
+## Usage Notes
+
+- Register new services and repositories as providers directly on `Container`; do not subclass it.
+- Inject the container into FastAPI (or the framework of your choice) via its `wire()` method in the app factory.
+- Keep transport-specific clients (e.g., third-party API clients) as additional `providers.Singleton` entries, bound to `config` for their credentials.

rpr/scaffolds/domain/settings.md

@@ -0,0 +1,57 @@
+## Domain Settings Template
+
+Target path: `packages/python/domain/src/{name_underscore}_domain/config/settings.py`
+
+Use this template when scaffolding the domain configuration layer. It provides a Pydantic `BaseSettings` class that loads from `.env` and defines all core infrastructure settings needed by the DI container.
+
+The first Python block is the generated file used by `rpr generate domain` and `rpr add template domain_settings`.
+
+```python
+from __future__ import annotations
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    db_host: str = Field(default="localhost", description="Database host")
+    db_port: int = Field(default=5432, description="Database port")
+    db_name: str = Field(default="postgres", description="Database name")
+    db_user: str = Field(default="postgres", description="Database user")
+    db_password: str = Field(default="", description="Database password")
+    db_sslmode: str = Field(default="prefer", description="Database SSL mode")
+    db_echo: bool = Field(default=False, description="Enable SQL query logging")
+    db_encrypt_key: bytes | None = Field(default=None, description="Fernet encryption key")
+
+    http_timeout: float = Field(default=30.0, description="HTTP client timeout in seconds")
+    httpx_max_connections: int = Field(default=100, description="Maximum HTTP connections")
+    http_max_keepalive: int = Field(default=20, description="Maximum keepalive HTTP connections")
+
+    @property
+    def database_url(self) -> str:
+        return (
+            f"postgresql+asyncpg://{self.db_user}:{self.db_password}"
+            f"@{self.db_host}:{self.db_port}/{self.db_name}"
+            f"?sslmode={self.db_sslmode}"
+        )
+```
+
+## What This Template Provides
+
+- Reads all settings from `.env` with `case_sensitive=False` and `extra="ignore"` so unknown keys never raise errors.
+- Defines the full set of database fields used to build `database_url` in the `@property`.
+- Defines `http_timeout`, `httpx_max_connections`, and `http_max_keepalive` so the container's `http_client` provider can bind them without extra lookups.
+- `db_encrypt_key` is `bytes | None` to pair with the `encrypted_column` utility when needed.
+
+## Usage Notes
+
+- Add corresponding keys to `.env.example` for each field (see `special_files.md` ENV section).
+- Extend `Settings` in the domain package to add app-specific fields; do not modify this base set.
+- `database_url` is a computed property — it is not read from `.env` directly.

rpr/scaffolds/instructions/all.instructions.md

@@ -0,0 +1,50 @@
+---
+applyTo: "**"
+description: "Project overview, monorepo structure, and tech stack for DDD architecture"
+---
+
+# Project Overview
+
+This project uses an NX + UV monorepo with a domain-driven design approach. Applications stay thin and delegate business logic to shared packages.
+
+## Architecture
+
+- **Applications** (`apps/*`): frontend apps, APIs, and other entry points. Keep them focused on transport, composition, and configuration.
+- **Packages**: shared domain logic, reusable UI code, Storybook, and Rust-backed engine code.
+- **Domain layer**: entities, DTOs, repositories, services, workflows, and dependency injection. Keep boundaries explicit and data flow predictable.
+
+## Tech Stack
+
+- NX for workspace orchestration
+- UV for Python environments and dependency management
+- React, TanStack Query, TanStack Router, and MUI on the Node/UI side
+- FastAPI, SQLModel, Alembic, and Dependency Injector on the Python side
+- Rust with PyO3 and Maturin for the engine package
+- Storybook for isolated UI development
+
+## Layout
+
+| Path                            | Purpose                                                                  |
+| ------------------------------- | ------------------------------------------------------------------------ |
+| `apps/{name}-web`               | Thin frontend application shell                                          |
+| `apps/{name}-api`               | FastAPI application                                                      |
+| `packages/node/{name}-ui`       | Reusable UI package with components, hooks, services, and state          |
+| `packages/node/sb`              | Storybook package                                                        |
+| `packages/python/domain`        | Python domain package containing the `src/{name_underscore}_domain` code |
+| `packages/python/{name}-engine` | Rust engine package exposed to Python                                    |
+
+## Instructions, Templates, and Scaffolds
+
+- Instruction files describe when to use a pattern and what constraints to follow.
+- `setup-guide.instructions.md` captures the NX + UV workspace contract for root setup, project layout, naming, and expected command surfaces.
+- `tooling.instructions.md` defines workspace-wide linting, formatting, and pre-commit conventions.
+- `tooling-setup.instructions.md` contains detailed setup guidance for root tooling files such as `pyproject.toml`, `nx.json`, `.pre-commit-config.yaml`, and `eslint.config.mjs`.
+- Shared utility implementations should live in stable project paths so code can reuse them instead of duplicating the same helpers in multiple places.
+- Files in `.github/scaffolds/` are reference examples. Use them as guidance if they exist, but do not force the codebase to match them when local conventions already differ.
+
+## Path-Specific Instructions
+
+- **API**: `api.instructions.md` for routes, dependency injection, and error handling
+- **Domain**: `domain.instructions.md` for entities, DTOs, repositories, services, and workflows
+- **Frontend**: `frontend.instructions.md` for React, TanStack Query, TanStack Router, and MUI patterns
+- **Rust engine**: `rust-engine.instructions.md` for PyO3, Maturin, and NX engine targets

rpr/scaffolds/instructions/api.instructions.md

@@ -0,0 +1,42 @@
+---
+applyTo: "apps/*-api/**"
+description: "FastAPI route patterns, dependency injection, and CRUD conventions"
+---
+
+# API Conventions
+
+Framework: FastAPI.
+
+When creating or modifying `main.py`, use `.github/scaffolds/api/main.py` as a reference if it exists. Follow the same overall shape: app factory, lifespan wiring, middleware registration, and exception handlers.
+
+## Routes
+
+- Keep route handlers thin: validate input, delegate to workflows or services, and translate the result into the response.
+- Prefer one `APIRouter()` per route module.
+- Set `response_model` on every public route.
+- For typed parameters, prefer `Annotated[...]` with FastAPI helpers such as `Path`, `Query`, and `Body`.
+- Request and response DTOs should use the project's JSON-model base so Python field names stay idiomatic while serialized JSON stays consistent.
+
+## Dependency Injection
+
+- Use `@inject` with `Depends(Provide[Container.<service_name>])` for services resolved from the container.
+- Do not instantiate repositories or domain services directly in route handlers.
+- Wire modules during startup or lifespan setup, not lazily inside request handlers.
+
+## Error Handling
+
+- Use `HTTPException(404)` for missing resources and other explicit `HTTPException` responses for expected client-facing failures.
+- Log unexpected failures and convert them to the project's standard server-error response path.
+- Do not use bare `except`; catch specific exceptions and keep error translation close to the boundary.
+
+## CRUD
+
+- Check existence before update or delete operations.
+- Use the correct HTTP status codes: `201` for create, `200` for successful reads or updates, and `204` for deletes with no body.
+- Return DTOs from route handlers, never ORM entities.
+- For partial updates, use a DTO with optional fields and apply the changes through `apply_partial_update` rather than hand-written field assignment.
+
+## Boundaries
+
+- Route modules own HTTP concerns. They should not contain business workflows, persistence logic, or cross-service orchestration.
+- Keep response shaping close to the route layer and business rules in the domain layer.

rpr/scaffolds/instructions/domain.instructions.md

@@ -0,0 +1,93 @@
+---
+applyTo: "packages/python/domain/**"
+description: "Domain layer structure, entities, DTOs, repos, and workflows"
+---
+
+# Domain Layer
+
+Use a DDD-style domain layer with explicit boundaries, SQLModel entities, Dependency Injector for composition, and Alembic for schema changes.
+
+## Structure
+
+- **entities**: SQLModel-based persistence models. Use the shared base entity pattern for ids and timestamps.
+- **dtos**: request, response, and integration models.
+- **repos**: data-access layer. Extend the shared base repository pattern.
+- **services**: external clients and provider integrations. Keep transport-specific logic here, not in workflows.
+- **workflows**: business use cases and multi-step orchestration. Pub/sub handlers belong in `workflows/handlers` when the project uses them.
+- **config**: settings, dependency-injection container, URLs, and logging.
+
+## Utilities
+
+- Keep shared domain utilities in `src/{name_underscore}_domain/utils/`.
+- Use `apply_partial_update()` from `utils/partial_update.py` for PATCH-style entity updates instead of handwritten field assignment.
+- Use `Mapper` and the `mapper` decorator from `utils/mapper_util.py` when repository methods should support both raw ORM access and `.to_dto()` conversion.
+- Use `DtoHelper` and `dto_helper` from `utils/dto_util.py` when the same DTO mapper should support both single models and lists.
+- Use `EncryptedColumn` from `utils/encrypted_column.py` for encrypted persisted values.
+
+## Reference Scaffolds
+
+When creating or modifying shared domain primitives, use the matching file in `.github/scaffolds/domain/` as a reference implementation if it exists.
+
+- `BaseEntity`: use `.github/scaffolds/domain/base_entity.md` as a reference for ids, timestamps, and SQLModel defaults.
+- Base repository pattern: use `.github/scaffolds/domain/base-repo.md` as a reference for shared repository behavior.
+
+These scaffold files are examples, not strict requirements. Prefer existing project-local conventions if the codebase already differs.
+
+## Migrations
+
+- Do not create Alembic migration files by hand.
+- Prefer the workspace migration command so schema changes run through the same project wiring as the rest of the repo.
+- The standard target shape is an Nx `migrate` target on the domain project that executes `uv run alembic -c packages/python/domain/alembic.ini` from the workspace root.
+- Run migration commands from the workspace root and keep the standalone `--` separator between Nx arguments and Alembic arguments.
+
+```sh
+npx nx run domain:migrate -- revision --autogenerate -m "{number}_a_descriptive_message"
+npx nx run domain:migrate -- upgrade head
+npx nx run domain:migrate -- downgrade -1
+```
+
+- Keep the Alembic CLI under the project's configured Python environment.
+- Alembic autogeneration depends on model discovery, so make sure new entity modules are imported by the domain model registry such as `entities/__init__.py`.
+
+## Repository Pattern
+
+- Repositories should extend the project's shared base repository abstraction. Do not introduce competing base repository names or patterns in the same codebase.
+- The base constructor should receive the model type, engine, and default DTO mapper used by the repository.
+- Use the `@mapper` decorator when a repository method should support `.to_dto()` in addition to returning the raw ORM result.
+- Use `@mapper(dto_func=...)` only when a method needs a mapper different from the repository default.
+- For session management, prefer `async with AsyncSession(self.engine) as session`.
+- Methods suffixed with `_in_session` should work inside an existing session and should not commit on their own.
+
+## Entity Pattern
+
+- Entities inherit from `BaseEntity`.
+- Prefer server-side defaults where the database should own the value.
+- Always set `__tablename__` to the table name in the database.
+- Use `__table_args__` to define table-level concerns such as indexes, constraints, and schema.
+- Prefer SQLModel APIs. Use raw SQLAlchemy only when SQLModel does not expose what you need, such as `func.now()` or `func.gen_random_uuid()` for database-level defaults.
+
+## Service Pattern
+
+- Register new services in the DI `Container`.
+- Dependencies are injected through constructors, not ad hoc method parameters.
+- Use `get_logger(self.__class__.__name__)` for service-local logging.
+- Keep workflows responsible for multi-step business logic and coordination across services and repositories.
+
+## DTO Discipline
+
+- Reuse existing DTOs when the contract is the same. Do not create near-duplicate DTOs for every small variation.
+- DTOs exposed through the API should stay minimal and focused on the contract, not internal persistence details.
+- Mapper functions should live in the DTO or mapper layer and follow a clear `to_dto()` naming convention.
+- DTOs that are serialized to JSON should use the project's camelCase-aware base model.
+- DTOs that represent external-service payloads can use `TypedDict` when a Pydantic model would add unnecessary weight.
+- Internal data containers that are not serialized can use `@dataclass` when that is the simplest fit.
+
+## Log Injection Prevention
+
+- Add a shared `sanitize_for_log()` helper if the project does not already have one.
+- Sanitize untrusted values before logging them, especially identifiers and externally supplied strings.
+
+## Testing
+
+- Service and repository tests should verify DTO mapping behavior, including `.to_dto()` paths when `mapper_util` is in use.
+- Use `@pytest.fixture` for reusable test setup.

rpr/scaffolds/instructions/frontend.instructions.md

@@ -0,0 +1,97 @@
+---
+applyTo: "packages/node/*-ui/**,apps/*/**"
+description: "React components, TanStack Query/Router, MUI patterns"
+---
+
+# Frontend (UI Library)
+
+Use React for UI composition, TanStack Query for server-state workflows, TanStack Router for routing, and MUI for the component system.
+
+## Patterns
+
+- Use functional components.
+- Extract reusable behavior into hooks instead of duplicating component logic.
+- Prefer a shared base API service at `src/services/base/api.service.ts` when the UI package needs centralized fetch behavior.
+- Prefer a shared `useStateNavigation` hook at `src/hooks/useStateNavigation.ts` when UI state should persist in the URL.
+- Reuse existing components, hooks, and service patterns before introducing a new abstraction.
+- Use TanStack Query for server state and request lifecycles.
+- Organize API access per domain: service methods in `services/`, query hooks near stateful consumers or in shared hooks when reused broadly.
+- On successful mutations, update or invalidate the relevant query cache instead of forcing a full-page reload.
+
+## Reference Scaffolds
+
+- When creating or modifying the shared base API service at `src/services/base/api.service.ts`, use `.github/scaffolds/frontend/api.service.ts` as a reference if it exists.
+- When creating or modifying the shared `useStateNavigation` hook at `src/hooks/useStateNavigation.ts`, use `.github/scaffolds/frontend/useStateNavigation.ts` as a reference if it exists.
+- These scaffold files are examples, not strict requirements. Prefer existing project-local conventions if the UI package already differs.
+
+Example mutation pattern:
+
+```ts
+type User = {
+  id: string;
+  name: string;
+};
+
+export const useChangeName = (id: string, newName: string) => {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: () => userService.changeName(id, newName),
+    onSuccess: () => {
+      queryClient.setQueryData<User | undefined>(["user", id], (oldData) => {
+        if (!oldData) {
+          return oldData;
+        }
+
+        return {
+          ...oldData,
+          name: newName,
+        };
+      });
+    },
+  });
+};
+```
+
+## Routing
+
+- Use TanStack Router for type-safe route definitions.
+- Keep route configuration close to the app boundary. The UI library should not own application-only route composition.
+- Prefer explicit route trees built from `createRootRoute`, `createRoute`, `addChildren`, and `createRouter`.
+
+## Styling
+
+- If a component needs non-trivial custom styling, place it in a sibling `{Component}.styles.tsx` file.
+- Use Emotion through MUI's `styled` API and prefer template-literal or callback-based styled components over scattered inline style objects.
+
+Example:
+
+```ts
+export const SomeContainer = styled(Box)`
+  display: flex;
+`;
+```
+
+- Prefer theme-driven colors and tokens so light and dark mode stay consistent.
+- Let `Paper` and `Typography` carry default background and text colors unless a component has a specific design reason to override them.
+- Create and maintain a shared app theme instead of scattering palette decisions across components.
+- Use the `sx` prop sparingly. It is appropriate for one-off local adjustments or truly dynamic runtime values. Shared or repeated styles should move into the theme or a styled wrapper.
+- Components should not hard-code their own layout width unless the component's contract requires it. Let parent containers control sizing.
+- Prefer flexbox or grid for layout rather than margin-based positioning.
+- Extend MUI theme types through a declaration file in the UI package when custom tokens are required.
+
+## Typing
+
+- Type every API payload and mutation input.
+- Prefer `type` aliases for DTO-shaped data, `interface` for extendable service contracts, and classes only when the UI genuinely needs behavior.
+- For components with children, prefer `React.PropsWithChildren<T>` over manually re-declaring a `children` field.
+
+## Components
+
+- Use functional components.
+- Use `useLayoutEffect` only when the effect must run before paint, such as DOM measurement or URL synchronization. Use `useEffect` by default for ordinary side effects.
+- Keep components as small and focused as practical.
+- Isolate side effects into hooks or boundary components. Query hooks are the normal exception because they are already side-effect boundaries.
+- Prefer pure helpers and deterministic render logic where possible to keep testing straightforward.
+- Do not memoize by default. Add memoization only when render churn is measurable or the component contract clearly benefits from it.
+- Be deliberate about prop shape and state ownership to avoid unnecessary re-renders.