indigo
0acf9ddff2
- Pass episode_id filter to backend API instead of client-side filtering, reducing payload size when an episode is selected - Skip getShot refetch in ShotDetailPanel when initialShot prop is provided - Fix redundant DB query in list_shots: read project.custom_task_statuses directly from the already-fetched project object - Add missing indexes on Task.shot_id, Task.assigned_user_id, Task.deleted_at and Episode.project_id; add add_perf_indexes.py migration script to apply them to existing databases - Center login page layout - Update CLAUDE.md and AGENTS.md with correct venv path Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
120 lines
5.2 KiB
Markdown
120 lines
5.2 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
LinkDesk is a VFX/animation production management system. It has a FastAPI backend and a Vue 3 frontend, running as separate dev servers with a Vite proxy.
|
|
|
|
## Architecture
|
|
|
|
**Backend** (`backend/`) — FastAPI + SQLAlchemy (SQLite by default, configurable via `DATABASE_URL`).
|
|
- `main.py` — app entry point; mounts routers and static uploads.
|
|
- `database.py` — SQLAlchemy engine and `get_db` dependency.
|
|
- `models/` — SQLAlchemy ORM models (project, shot, asset, task, episode, user, notification, activity, api_key).
|
|
- `routers/` — one file per resource; each router is `include_router`'d with a prefix in `main.py`.
|
|
- `schemas/` — Pydantic request/response schemas (separate from models).
|
|
- `utils/` — shared helpers (file handling, notifications).
|
|
|
|
**Frontend** (`frontend/src/`) — Vue 3 + TypeScript + Pinia + Vue Router + shadcn-vue (Radix UI) + TanStack Table.
|
|
- `main.ts` — app bootstrap.
|
|
- `router/index.ts` — route definitions; guards enforce `requiresAuth`, role-based (`roles: [...]`), and admin-only (`adminPermission: 'required'`) access.
|
|
- `stores/` — Pinia stores (auth, projects, assets, tasks, episodes, notifications, user, settings, taskStatuses).
|
|
- `services/` — axios wrappers per resource (`api.ts` is the base client). All calls go through `/api` which Vite proxies to `http://localhost:8000`.
|
|
- `components/` — organized by domain (`asset/`, `shot/`, `project/`, `layout/`, `auth/`, `episode/`, `task/`) plus `ui/` for shadcn primitives.
|
|
- `views/` — page-level components; project detail uses nested child routes under `/projects/:projectId`.
|
|
- `composables/` — shared Vue composition logic (`useDetailPanel`, `useAvatarUrl`).
|
|
- `types/` — shared TypeScript interfaces.
|
|
|
|
**Auth flow**: JWT access + refresh tokens stored in `localStorage`. `api.ts` interceptor auto-refreshes on 401. Router guard initializes auth from stored token on first navigation.
|
|
|
|
**Role model**: `coordinator`, `director`, `developer` roles + `isAdmin` flag. Admin can access any role-gated route.
|
|
|
|
## Commands
|
|
|
|
### Backend
|
|
```bash
|
|
# venv is at repo root, not inside backend/
|
|
cd backend
|
|
..\venv\Scripts\activate # Windows PowerShell
|
|
# or run directly:
|
|
# D:\Repo\LinkDesk\.venv\Scripts\uvicorn.exe main:app --reload --port 8000
|
|
uvicorn main:app --reload --port 8000
|
|
```
|
|
|
|
### Frontend
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # http://localhost:5173
|
|
npm run type-check # TypeScript check (vue-tsc --noEmit)
|
|
npm run build
|
|
```
|
|
|
|
### Setup
|
|
Copy `.env.example` to `.env` in `backend/` and set `SECRET_KEY`. Database auto-creates on first run via SQLAlchemy `create_all`.
|
|
|
|
---
|
|
|
|
# CLAUDE.md — 12-rule template
|
|
|
|
These rules apply to every task in this project unless explicitly overridden.
|
|
Bias: caution over speed on non-trivial work. Use judgment on trivial tasks.
|
|
|
|
## Rule 1 — Think Before Coding
|
|
State assumptions explicitly. If uncertain, ask rather than guess.
|
|
Present multiple interpretations when ambiguity exists.
|
|
Push back when a simpler approach exists.
|
|
Stop when confused. Name what's unclear.
|
|
|
|
## Rule 2 — Simplicity First
|
|
Minimum code that solves the problem. Nothing speculative.
|
|
No features beyond what was asked. No abstractions for single-use code.
|
|
Test: would a senior engineer say this is overcomplicated? If yes, simplify.
|
|
|
|
## Rule 3 — Surgical Changes
|
|
Touch only what you must. Clean up only your own mess.
|
|
Don't "improve" adjacent code, comments, or formatting.
|
|
Don't refactor what isn't broken. Match existing style.
|
|
|
|
## Rule 4 — Goal-Driven Execution
|
|
Define success criteria. Loop until verified.
|
|
Don't follow steps. Define success and iterate.
|
|
Strong success criteria let you loop independently.
|
|
|
|
## Rule 5 — Use the model only for judgment calls
|
|
Use me for: classification, drafting, summarization, extraction.
|
|
Do NOT use me for: routing, retries, deterministic transforms.
|
|
If code can answer, code answers.
|
|
|
|
## Rule 6 — Token budgets are not advisory
|
|
Per-task: 4,000 tokens. Per-session: 30,000 tokens.
|
|
If approaching budget, summarize and start fresh.
|
|
Surface the breach. Do not silently overrun.
|
|
|
|
## Rule 7 — Surface conflicts, don't average them
|
|
If two patterns contradict, pick one (more recent / more tested).
|
|
Explain why. Flag the other for cleanup.
|
|
Don't blend conflicting patterns.
|
|
|
|
## Rule 8 — Read before you write
|
|
Before adding code, read exports, immediate callers, shared utilities.
|
|
"Looks orthogonal" is dangerous. If unsure why code is structured a way, ask.
|
|
|
|
## Rule 9 — Tests verify intent, not just behavior
|
|
Tests must encode WHY behavior matters, not just WHAT it does.
|
|
A test that can't fail when business logic changes is wrong.
|
|
|
|
## Rule 10 — Checkpoint after every significant step
|
|
Summarize what was done, what's verified, what's left.
|
|
Don't continue from a state you can't describe back.
|
|
If you lose track, stop and restate.
|
|
|
|
## Rule 11 — Match the codebase's conventions, even if you disagree
|
|
Conformance > taste inside the codebase.
|
|
If you genuinely think a convention is harmful, surface it. Don't fork silently.
|
|
|
|
## Rule 12 — Fail loud
|
|
"Completed" is wrong if anything was skipped silently.
|
|
"Tests pass" is wrong if any were skipped.
|
|
Default to surfacing uncertainty, not hiding it. |