# Shorty — Agent-oriented project guide

This file describes the repository layout, conventions, and workflows so LLM agents and humans can work in it accurately and efficiently.

## What this repo is

- **Shorty** is a self-hosted stack: **Kutt** (URL shortener) + **QR Designer** (qr-api + qr-web).
- **Kutt**: short links at `mifi.me`, admin at `link.mifi.me` (Postgres + Redis).
- **QR Designer**: Next.js app at `qr.mifi.dev` (BasicAuth); backend **qr-api** (Express, SQLite, uploads, shorten proxy to Kutt). qr-api is internal-only (backend network).

## Repo layout (monorepo, pnpm workspace)

```
shorty/
├── package.json              # Root: scripts lint, format, format:check, test, build (all delegate to workspaces)
├── pnpm-workspace.yaml       # packages: qr-api, qr-web
├── docker-compose.yml       # Full stack with build (Kutt + qr-api + qr-web from Dockerfiles)
├── docker-compose.portainer.yml  # Same stack using registry images; for Portainer + webhook redeploy
├── .woodpecker/
│   ├── ci.yml               # CI: install → format → lint → test → build
│   └── deploy.yml           # Deploy: buildx qr-api + qr-web (multi-arch), push, Portainer webhook
├── qr-api/                  # Express API (TS), SQLite, multer uploads, Kutt proxy
│   ├── Dockerfile
│   ├── .dockerignore
│   ├── src/
│   └── package.json
└── qr-web/                  # Next.js 15 (App Router), Mantine, qr-code-styling
    ├── Dockerfile
    ├── .dockerignore
    ├── next.config.ts       # output: 'standalone'
    ├── src/
    └── package.json
```

- **No root Dockerfile.** Images are built from `qr-api/` and `qr-web/` only.
- **Lockfile:** `pnpm-lock.yaml` is committed; CI uses `pnpm install --frozen-lockfile`.

## Key scripts (from repo root)

| Command           | Effect |
|-------------------|--------|
| `pnpm install`    | Install deps for all workspaces |
| `pnpm run lint`   | ESLint in qr-api and qr-web |
| `pnpm run format:check` | Prettier check (no write) |
| `pnpm run format`  | Prettier write |
| `pnpm run test`   | Vitest in qr-api and qr-web |
| `pnpm run build`  | Build qr-api (tsc) and qr-web (next build) |

Per-package: `pnpm --filter qr-api dev`, `pnpm --filter qr-web dev` (dev servers).

## Environment and config

- **Root:** `.env.example` documents vars; copy to `.env` for Docker Compose. `.env` is gitignored.
- **Devcontainer:** `.devcontainer/devcontainer.json` sets `DB_PATH`, `UPLOADS_PATH`, `KUTT_API_KEY`, `QR_API_URL` for in-container dev; no `.env` required for qr-api/qr-web dev.
- **Compose:** Kutt needs `DB_PASSWORD`, `JWT_SECRET`; qr-api optionally `KUTT_API_KEY`. Portainer stack can set `REGISTRY`, `IMAGE_TAG` for registry-based compose.

## CI/CD (Woodpecker)

- **CI** (runs on PR, push to main, tag, manual): Node 22, pnpm, then `format:check` → `lint` → `test` → `build`. No Docker in CI.
- **Deploy** (runs on main push/tag/manual after CI): Uses `docker buildx` to build **two** images from `./qr-api` and `./qr-web` with `--platform linux/amd64,linux/arm64`, tags `:latest` and `:${CI_COMMIT_SHA}`, pushes to `git.mifi.dev/mifi-holdings/shorty-qr-api` and `shorty-qr-web`, then POSTs `portainer_webhook_url` to trigger Portainer stack redeploy.
- **Secrets:** `gitea_registry_username`, `gitea_package_token`, `portainer_webhook_url`.

## Portainer (production)

- **Registry-based stack:** Use `docker-compose.portainer.yml`. Images: `${REGISTRY}/mifi-holdings/shorty-qr-api:${IMAGE_TAG}`, same for `shorty-qr-web`. Add stack webhook in Portainer and set that URL as `portainer_webhook_url` in Woodpecker.
- **Build-from-source:** Use `docker-compose.yml`; no registry, no webhook.

## Code style and tooling

- **TypeScript** only (qr-api and qr-web).
- **Prettier:** 4 spaces, single quotes, trailing comma all, semicolons (see `.prettierrc`). Check with `pnpm run format:check`.
- **ESLint:** Root `.eslintrc.cjs` for qr-api; qr-web has its own `.eslintrc.cjs` (Next + Prettier). No TSLint.
- **Ignores:** `.gitignore` (e.g. node_modules, .pnpm-store, .next, dist, .env, *.tsbuildinfo); `.prettierignore` and ESLint `ignorePatterns` aligned (coverage, build dirs, .pnpm-store). Each app has `.dockerignore` to keep build context small.

## Where to change what

- **API routes (qr-api):** `qr-api/src/routes/`, `qr-api/src/index.ts`.
- **Web app (qr-web):** `qr-web/src/app/` (App Router), `qr-web/src/components/`, `qr-web/src/contexts/`.
- **Shared types:** Defined in each package; no shared package.
- **Compose:** Kutt + qr services in `docker-compose.yml`; registry-only variant in `docker-compose.portainer.yml`.
- **Pipelines:** `.woodpecker/ci.yml`, `.woodpecker/deploy.yml`. Image names and registry are in `deploy.yml` env.

## Testing and building locally

- **Unit tests:** `pnpm run test` (Vitest in both packages).
- **Dev:** `pnpm --filter qr-api dev` and `pnpm --filter qr-web dev` (ports 8080 and 3000); devcontainer forwards them.
- **Full stack (Docker):** `docker compose up -d` (uses `docker-compose.yml`; needs `.env` with `DB_PASSWORD`, `JWT_SECRET`).
- **Multi-arch build (local):** Use `docker buildx build --platform linux/amd64,linux/arm64 -t <repo>:<tag> --push ./qr-api` (and same for `./qr-web`) after logging into the registry.

This layout and these scripts are the source of truth for automation and agent-driven edits.