Skip to content

Open source personal finance application

docs(claude): slim instructions and reference detailed docs

Ilya Komichev68429ccc1248
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.md
index 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` |
+
## Development
Run the Convex backend and the Nuxt app in separate terminals: