Open source personal finance application
docs(claude): slim instructions and reference detailed docs
Ilya Komichev68429ccc1248
diff --git a/CLAUDE.md b/CLAUDE.mdindex 291faf65..3d7a3a88 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,64 +1,36 @@# Finapp-Personal finance app. Nuxt 4, Vue 3, Pinia, @nuxt/ui v4 (Tailwind CSS v4), Convex backend, Better Auth.+Personal finance app. Nuxt 4, Vue 3, Pinia, @nuxt/ui v4 (Tailwind CSS v4), Convex backend, Better Auth. Repo is a pnpm monorepo: `app/` (`@finapp/app`, Nuxt source under `app/app/`, Convex backend under `app/convex/`) and `docs/` (`@finapp/docs`).- Node.js >= v24.12.0- Package manager: pnpm- SPA mode (`ssr: false`)-- PWA with `generateSW` strategy from `@vite-pwa/nuxt` (no custom service worker)+- PWA with `generateSW` strategy from `@vite-pwa/nuxt`## Commands- `pnpm dev` - Nuxt dev server on port 3050- `pnpm dev:convex` - Convex backend (watches and auto-deploys changes)- Both must run simultaneously in separate terminals-- `pnpm build` - SPA build (`nuxt build`)-- `pnpm generate` - static generation (`nuxt generate`)+- `pnpm build` - SPA build+- `pnpm generate` - static generation- `pnpm lint` / `pnpm lint:fix` - ESLint- `pnpm test` - Vitest-- `pnpm docs:dev` - docs dev server-- `pnpm docs:build` - build docs site--## Project Structure--See [Architecture](docs/content/en/3.technical/1.architecture.md) for detailed project structure and file descriptions.+- `pnpm docs:dev` / `pnpm docs:build` - docs site## Conventions- Components: PascalCase, grouped by feature in `components/[feature]/`- UI primitives in `components/ui/`-- Imports use `~/` alias (resolves to `/app/`)+- Imports use `~/` alias (resolves to `app/app/`)- ESLint flat config with `@antfu/eslint-config`, Perfectionist for sorting- Prettier with Tailwind plugin, single quotes, no semicolons, trailing commas- i18n: `no_prefix` strategy, two locales (en-US, ru-RU)- Always run `pnpm lint:fix` before committing-## CSS / Theme Rules--- @nuxt/ui defines CSS vars in `@layer theme`-- Dynamic theme (radius, colors) is applied via `useHead()` in `app.vue` with `tagPriority: -2`-- **Do NOT** set `--ui-radius` or `--ui-primary` in `theme.css` - non-layered CSS loads after `useHead()` and overrides it-- Radius uses `??` (not `||`) to allow `0`: `${appConfig.theme.radius ?? 0.375}`--## Store Pattern--All Pinia stores (`useTrnsStore`, `useWalletsStore`, `useCategoriesStore`) follow the same pattern:--- `items: shallowRef` - reactive state (shallow for performance)-- `init()` - fetch from Convex → `mergeOfflineOps` → `set`-- `set(data)` - `items.value = data` + `debouncedPersist` (300ms)-- `save({ id, values })` - optimistic UI → `pushSaveOp` → fire mutation (no await)-- `delete(id)` - optimistic UI → `pushDeleteOp` → fire mutation (no await)--Mutation result: `.then()` removes offline op + remaps frontend ID → `.catch()` shows error toast.--### Frontend ID System--New entities get temporary IDs with `local_` prefix (e.g., `local_a1b2c3`). `isLocalId(id)` checks `id.startsWith('local_')` to distinguish from Convex IDs. After successful create mutation, `handleMutationResult()` remaps `items[localId]` → `items[convexId]`.-## Convex Backend-- Schema in `convex/schema.ts`: categories, wallets, trns, userSettings, rates+- Schema in `app/convex/schema.ts`: `categories`, `wallets`, `trns`, `userSettings`, `rates`, `syncMeta`, `tombstones`- `TrnType` enum in `convex/validators.ts` (re-exported from `convex/shared.ts`): Expense (0), Income (1), Transfer (2)- Adjustment is determined by `categoryId === 'adjustment'`, NOT by `TrnType`. It uses Expense or Income type, excluded from income/expense statistics- Auth: `@convex-dev/better-auth` with `cors: true` in `http.ts`@@ -67,97 +39,17 @@ New entities get temporary IDs with `local_` prefix (e.g., `local_a1b2c3`). `isL### Convex Client Access+Both composables live in `app/app/composables/useConvex.ts`:+| Composable | Returns | Purpose ||------------|---------|---------|| `useConvexClient()` | `ConvexClient` | WebSocket client || `useConvexClientWithApi()` | `{ api, client }` | Client + typed `api` object for queries/mutations |-- Stores use imperative `client.query()` and `client.mutation()` because they manage their own caching and offline merge--### Auth Flow--Auth uses Better Auth with `convexClient()` and `crossDomainClient()` plugins (`composables/useAuth.ts`).--**Convex auth lifecycle** (`plugins/convex.ts`):-1. Eagerly call `client.setAuth(fetchToken)` if `hasAuthCookie()` && online - starts token fetch in parallel with session resolution-2. `fetchToken` calls `authClient.convex.token()` - the `crossDomainClient` plugin handles cookie forwarding automatically-3. `authReadyPromise` resolves when the first token fetch completes (success or failure); consumers (`loadDataFromDB`) await this before issuing queries-4. Session watch acts only on definitive results - ignores `isPending` and `error` states to prevent logout on network failures-5. `online` event re-creates `authReadyPromise` and calls `setAuth()` for fresh token-6. `ensureConvexAuth()` - called from callback page to set auth BEFORE SPA navigation--**Auth cookie** (`composables/useAuthCookie.ts`): `finapp.localAuthUid` cookie (document.cookie, 1yr max-age) - fast synchronous check for auth state. Not a security token, just a hint for middleware and plugin to skip network calls.--### Convex CLI Notes--- **Targeting prod**: always use the `--prod` flag (`npx convex run --prod`, `npx convex export --prod`). Do NOT use `CONVEX_DEPLOYMENT` env var - `.env.local` overrides env vars, so the CLI silently hits dev instead of prod-- Convex rejects hyphens in directory names (use underscores: `test_utils/`)-- Files with multiple dots (e.g., `setup.helper.ts`) are auto-skipped by Convex bundler - useful for test helpers-- Deploy with `--typecheck=disable` if there are pre-existing TS errors in Convex functions--## Local Development Setup--1. Install dependencies: `pnpm install`-2. Start Convex backend: `pnpm dev:convex` - connects to dev deployment, watches and auto-deploys changes-3. Start Nuxt frontend: `pnpm dev` - runs on http://localhost:3050-4. Both servers must run simultaneously (in separate terminals)--### First-time setup--Convex dev deployment env vars must be configured (one-time):--```sh-npx convex env set BETTER_AUTH_SECRET <value>-npx convex env set APP_URL http://localhost:3050-npx convex env set GOOGLE_CLIENT_ID <value>-npx convex env set GOOGLE_CLIENT_SECRET <value>-npx convex env set OPEN_EXCHANGE_RATES_KEY <value>-```--## Environment Variables--### Env files--- `.env` - dev deployment values, read by Nuxt (default `--dotenv`)-- `.env.local` - auto-created by `convex dev`, used by Convex CLI (gitignored)-- `.env.prod` - prod deployment values, used by `pnpm dev:prod`--All `.env*` files are gitignored except `.env.example`.--### Nuxt env vars (in `.env` / `.env.prod`)--- `CONVEX_DEPLOYMENT` - deployment identifier (used by Convex CLI)-- `VITE_CONVEX_URL` - Convex deployment URL (Nuxt frontend)-- `VITE_CONVEX_SITE_URL` - Convex site URL (Nuxt auth client)--### Convex backend env vars (set via `npx convex env set`)--- `BETTER_AUTH_SECRET` - secret key for Better Auth (**required** - without it all auth endpoints including CORS preflight will fail)-- `APP_URL` - app URL for cross-domain auth and CORS/trustedOrigins-- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` - Google OAuth-- `OPEN_EXCHANGE_RATES_KEY` - exchange rates API--## Key Files--| What | Where |-|------|-------|-| App entry | `app/app.vue` |-| Theme logic | `app/plugins/theme.ts`, `app/app.vue` |-| Auth setup | `app/plugins/convex.ts`, `app/composables/useAuth.ts` |-| Auth cookie | `app/composables/useAuthCookie.ts` |-| Auth guard | `app/middleware/auth.global.ts`, `app/components/user/useGuard.ts` |-| Store sync | `app/composables/useStoreSync.ts` |-| Offline queue | `app/components/offline/helpers.ts` |-| Offline replay | `app/components/offline/replay.ts` |-| Statistics calc | `app/components/amount/getTotal.ts` |-| Convex schema | `convex/schema.ts` |-| Frontend IDs | `app/utils/convexId.ts`, `utils/generateId.ts` |-| Date utils | `app/components/date/utils.ts` |-| Menu state | `app/components/layout/useMenuData.ts` |-| Bottom sheet drag | `app/components/bottomSheet/useBottomSheetDrag.ts` |+Stores use imperative `client.query()` and `client.mutation()` because they manage their own caching and offline merge.## Documentation-Built with [Docus](https://docus.dev/) in `../docs/` directory. Content in `../docs/content/en/` and `../docs/content/ru/`.--For detailed architecture, auth flows, offline queue, and sync strategy see `../docs/content/en/3.technical/`.+- Setup, env vars, scripts: `README.md`+- Architecture, store pattern, sync, offline queue, auth flow: `docs/content/en/3.reference/`+- Convex CLI gotchas, Better Auth incident fixes: `docs/content/en/2.development/08.troubleshooting.md`diff --git a/README.md b/README.mdindex 386424ba..aa59d9d6 100644--- a/README.md+++ b/README.md@@ -116,6 +116,16 @@ pnpm --filter @finapp/app exec convex env set OPEN_EXCHANGE_RATES_KEY your_app_i`BETTER_AUTH_SECRET` is required. Without it, auth endpoints, including CORS preflight requests, will fail.+### Environment files++The app workspace uses several `.env` files (all gitignored except `.env.example`):++| File | Purpose |+| --- | --- |+| `app/.env` | Dev deployment values, read by Nuxt |+| `app/.env.local` | Auto-created by `convex dev`, used by the Convex CLI |+| `app/.env.prod` | Prod deployment values, used by `pnpm dev:prod` |+## DevelopmentRun the Convex backend and the Nuxt app in separate terminals: