LinkDesk/AGENTS.md

AGENTS.md

Guidance for AI coding agents working in this repository.

Project Overview

LinkDesk is a VFX/animation production management system: FastAPI backend + Vue 3 frontend, run as separate dev servers with a Vite proxy bridging them.

Architecture

Backend (backend/) — FastAPI + SQLAlchemy (SQLite by default, set via DATABASE_URL env var).

• main.py — entry point; registers all routers and mounts /uploads static dir.
• database.py — SQLAlchemy engine and get_db session dependency.
• models/ — ORM models: project, shot, asset, task, episode, user, notification, activity, api_key.
• routers/ — one file per resource, each prefixed in main.py.
• schemas/ — Pydantic request/response schemas (separate from ORM models).
• utils/ — shared helpers (file handling, notifications).

Frontend (frontend/src/) — Vue 3 + TypeScript + Pinia + Vue Router + shadcn-vue + TanStack Table.

• router/index.ts — routes with requiresAuth, role (roles: [...]), and admin-only (adminPermission: 'required') guards.
• stores/ — Pinia stores per domain (auth, projects, assets, tasks, episodes, notifications, user, settings, taskStatuses).
• services/ — axios wrappers per resource; api.ts is the base client. All calls use /api prefix, proxied by Vite to http://localhost:8000.
• components/ — domain folders (asset/, shot/, project/, layout/, auth/, episode/, task/) + ui/ for shadcn primitives.
• views/ — page-level components; project detail uses nested child routes under /projects/:projectId.
• composables/ — shared composition logic.
• types/ — shared TypeScript interfaces.

Auth: JWT access + refresh tokens in localStorage. api.ts interceptor auto-refreshes on 401. Router guard initializes auth from stored token on first navigation.

Roles: coordinator, director, developer + isAdmin flag. Admins can access any role-gated route.

Commands

Backend

cd backend
# Windows: .venv\Scripts\activate  |  bash/mac: source .venv/bin/activate
uvicorn main:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev          # http://localhost:5173
npm run type-check   # vue-tsc --noEmit
npm run build

First-time setup

Copy backend/.env.example to backend/.env and set SECRET_KEY. The database schema is created automatically on first run via Base.metadata.create_all.

Coding conventions

• Backend: follow existing router/schema/model separation. Pydantic schemas live in schemas/, ORM models in models/. Never mix them.
• Frontend: services call the API; stores hold state; components consume stores. Don't call apiClient directly from components.
• Use @/ alias for all frontend imports (maps to frontend/src/).
• Match existing style exactly — don't refactor adjacent code while fixing something.
• Minimum code that solves the problem. No speculative features or abstractions.