# Repository Guidelines

## Project Structure & Module Organization
- Root: orchestration (`podman-compose*.yml`), container builds (`Dockerfile*`), `start.sh`, `.env.example` for Canva credentials/scopes.
- Frontend: `frontend/` (Vue 3 + Pinia + Vite). Source in `frontend/src/` (`components/`, `views/`, `stores/`, `router/`, `services/`). Builds land in `frontend/dist/`.
- Canva App: `canva-app/` (React + Canva Apps SDK) served on port 8080 for in-Canva panel tests.
- Go API: `server-go/` (Go 1.25). `main.go` exposes OAuth (`/auth/canva/*`) and design proxies (`/designs`, `/designs/{id}`, `/designs/start-session`).

## Build, Test, and Development Commands
- Install deps: `pnpm install` (root) — populates `frontend/` and `canva-app/`.
- Frontend dev: `pnpm dev` (or `cd frontend && pnpm dev`) -> Vite on port 3000.
- Frontend builds: `pnpm build` (app), `pnpm build-lib` (library), `pnpm preview` to serve the built app.
- Canva App dev: `pnpm canva-app:dev` -> Vite on port 8080; build with `pnpm canva-app:build`.
- Lint/format: `pnpm lint` and `pnpm format`.
- API local run: `go run ./server-go` (requires Go 1.25+, env vars below).
- Containers (recommended): `./start.sh` or `podman compose -f podman-compose.dev.yml up --build`. Compose auto-installs deps in each container and mounts:
  - `./frontend -> /home/node/app/frontend`
  - `./canva-app -> /home/node/app/canva-app`
  - API binary from `Dockerfile.api`

## Coding Style & Naming Conventions
- JavaScript/Vue: 2-space indent; ESLint + Prettier + Tailwind plugin via `pnpm lint`. Use `@/` alias and keep Canva API calls in `frontend/src/services`.
- Go: standard `gofmt`; keep handlers small and prefer helper helpers for Canva HTTP proxying.
- No mock/fake endpoints—keep code paths aligned with live Canva Connect API.

## Testing Guidelines
- Tests: prefer Vitest, Playwright (`frontend/tests/`), and `go test ./...` for API code. Add a happy-path and one Canva error case per feature.

## Commit & Pull Request Guidelines
- Use imperative, descriptive messages; Conventional Commit prefixes (`feat:`, `fix:`, `chore:`) are encouraged for changelog clarity.
- Before a PR: run `pnpm lint`, relevant tests, and `pnpm build`; for API changes, ensure `go test ./...` passes if tests exist.
- PRs should state intent, linked issues, environment/config changes, and screenshots or GIFs for UI updates.

## Configuration & Security
- Copy `.env.example` to `.env`; set `CANVA_CLIENT_ID`, `CANVA_CLIENT_SECRET`, `CANVA_SCOPES` (space-separated, approved list), `VITE_API_BASE` (`http://127.0.0.1:4000` by default), optional `CANVA_REDIRECT_URI`, `FRONTEND_SUCCESS_URL`, `FRONTEND_ORIGIN`.
- Scopes are not defaulted—missing or invalid scopes break auth. Align redirect/origin with Canva dashboard and the dev compose ports (3000/4000).
- Never commit real secrets or tokens. Rotate immediately if exposed and update the Canva app credentials.