Add CLAUDE.md and AGENTS.md with codebase architecture and dev commands

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-06-19 04:03:47 +08:00
parent 19bc4e8a23
commit 0dd37d1706
2 changed files with 177 additions and 0 deletions
@@ -0,0 +1,59 @@
+# 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
+```bash
+cd backend
+# Windows: .venv\Scripts\activate  |  bash/mac: source .venv/bin/activate
+uvicorn main:app --reload --port 8000
+```
+
+### Frontend
+```bash
+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.