engineering-conventions

name	engineering-conventions
description	RAGAPPv3 engineering conventions — backend (FastAPI + SQLite + LanceDB), frontend (React + TypeScript + Vite + Vitest), database/migration/RBAC patterns, and the multi-agent skill layout. Load before implementing or refactoring backend routes/services/migrations or frontend pages/components, or when you need to know "how does this repo do X".

RAGAPPv3 Engineering Conventions

The authoritative, detailed conventions live in docs/engineering/conventions.md. Read it before non-trivial backend or frontend work. Match the pattern in the file you are editing over anything summarized here.

Must-know invariants (summary)

Backend (backend/app/)

• Routes export router = APIRouter(), registered in app/main.py with prefix="/api". Inject deps via Depends(...) (get_db, get_vector_store, get_current_active_user, get_evaluate_policy).
• Request/response shapes are Pydantic BaseModel. Errors via raise HTTPException(status_code, detail). Register static routes before dynamic {id} routes to avoid shadowing.
• All connections come from SQLiteConnectionPool with PRAGMA foreign_keys = ON — rely on ON DELETE CASCADE. Schema is the SCHEMA constant; migrations are idempotent migrate_add_* functions registered in run_migrations.
• SQLite is sync; wrap blocking calls in await asyncio.to_thread(...). Atomic multi-statement writes use BEGIN IMMEDIATE (clear any dangling tx with if conn.in_transaction: conn.rollback() first).
• Authorize via await evaluate(user, "vault", vault_id, action); scope every user-data query by vault.
• evaluate_policy vs _evaluate_policy: There are two variants. _evaluate_policy(db, principal, resource_type, resource_id, action) accepts an injected DB connection — use this in FastAPI dependency chains. evaluate_policy(principal, resource_type, resource_id, action) opens its own pool connection — legacy backward-compatibility variant. require_vault_permission at backend/app/api/deps.py:476 still uses the standalone variant, which doubles per-request connection consumption under load. When adding new auth dependencies, prefer the DI-injected get_evaluate_policy.

Frontend (frontend/src/)

• Single axios client in lib/api.ts (VITE_API_URL, Bearer + CSRF interceptors). Prefer options-object function signatures. IDs are typed as declared in api.ts (Document.id is a string).
• Pages are slim orchestrators composing local hooks + feature components (the DocumentsPage pattern). State via Zustand. Routes are lazy + ProtectedRoute + MainAppShell.
• strict TS, zero-warning lint (eslint src --max-warnings 0). Scripts: typecheck, lint, test (vitest run), build.

Repo

• Three agent runners, three skill trees (.claude/, .agents/, .opencode/). Mirror repo-specific skills across all three, or keep them thin pointers to canonical docs.
• Before push/PR: run ci-compatibility-audit. For tests: writing-tests / docs/engineering/testing.md. For commits/PRs: commit-pr.

Hugeicons + lucide mixed icon discrimination

• The navigation rail (NavigationRail.tsx) mixes @hugeicons/core-free-icons icons (type IconSvgElement — a readonly array) with lucide-react icons (type React.ComponentType, rendered as forwardRef objects). When adding new nav items or any component that accepts a ComponentType | IconSvgElement union, discriminate with Array.isArray, NOT typeof === "function". Lucide forwardRef components have typeof === "object", not "function" — the wrong guard routes them to HugeiconsIcon, which spreads its icon prop ([...icon]) and throws TypeError: currentIcon is not iterable at render time on every authenticated page.
• Canonical pattern: function isHugeicon(icon): icon is IconSvgElement { return Array.isArray(icon); } — use this as a JSX type guard.
• HugeiconsIcon is safe for any prop that resolves to an actual hugeicons array export. Never pass a React component type to it, even if it looks like a valid JSX element.

TypeScript tsconfig boundary (Vite context)

• tsconfig.node.json covers only vite.config.ts. tsconfig.json covers src/ and references tsconfig.node.json as a composite project.
• Do NOT add files from src/ to tsconfig.node.json's include array and do NOT import src/ files from vite.config.ts or vite.paths.ts. Doing so produces Output file has not been built from source file — a TypeScript composite conflict because both tsconfigs would include the same file.
• When logic must be shared between vite.paths.ts and src/lib/, keep two copies with cross-reference comments. The subpath deployment helpers (normalizeBasePath) follow this pattern: canonical source in src/lib/normalize-base-path.ts, inline duplicate in vite.paths.ts.

See docs/engineering/conventions.md for the full detail and file references.