LinkDesk/CLAUDE.md

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

cd backend
# Activate venv first (Windows)
.venv\Scripts\activate   # or: source .venv/bin/activate on bash
uvicorn main:app --reload --port 8000

Frontend

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.