# indep-ai / indepai.app
CloudFloo product. Site: <https://indepai.app>.
## Product summary
**IndepAI** is a global FIRE (Financial Independence, Retire Early) calculator targeted at digital nomads and "FI-curious" mainstream users. Core pitch: *"Show me where in the world I can reach FI fastest."*
- **0–1000 FI Score** — gamified single-number readout of a user's FI progress, broken into FI Progress, Passive Income, Savings Rate, and Geo Efficiency.
- **Cities Explorer** — 1100+ cities with cost-of-living, quality, and nomad data; drives the geo-arbitrage comparison.
- **Geo-arbitrage comparer** — 3 free / unlimited paid; the differentiator.
- **AI Coach** — OpenRouter-backed personalized advice across 8 categories, rate-limited and cost-tracked.
- **Milestone badges** — 7 tiers (Seedling → Fully FI), shareable with server-rendered OG images and referral links (viral loop).
- **Stripe-billed freemium** — Free / Starter / Pro / Premium, monthly + yearly.
- **Primary persona**: "Everyday Emma" (28–40, traditional job, never heard of FIRE) — educational entry point. Secondary: "Curious Casey" (FI-curious researcher).
- **6-month business targets** (per PRD v2.2): 5k signups, 2k MAU, 3–5% free→paid, 10k+ FI scores calculated, 1k+ social shares.
## Tech stack
- **Frontend**: Astro 5.17 (file-based routing, server endpoints) + React 19 islands. Tailwind CSS 4 + shadcn/ui. Three.js / R3F for 3D bits, Remotion for video, Leaflet for maps.
- **Backend**: Astro server routes under `src/pages/api/v1/`. Supabase (PostgreSQL + Auth + RLS). Stripe for billing. Resend + React Email for transactional mail. Sentry v10 for errors. ioredis, prom-client (Node-only, stubbed in client builds).
- **AI**: OpenRouter (`@openrouter/ai-sdk-provider`), `ai` SDK, OpenAI fallback, Gemini for image generation.
- **Validation**: Zod (`@asteasolutions/zod-to-openapi` for OpenAPI from Zod schemas).
- **Tooling**: TypeScript 5.9, ESLint 9, Prettier, Knip, Husky + lint-staged. Vitest for unit, Playwright for E2E, Cucumber for acceptance.
- **Infra**: Docker → Kubernetes via Kustomize (`infra/k8s/{base,overlays}`), GitOps via ArgoCD (<https://argocd.cloudfloo.io/>). GitHub Actions CI.
- **Docs site**: Starlight subsite under `docs/`, built and integrated into the main app build.
- **Marketing**: Remotion video pipelines (`video/`), n8n workflows, ad/SEO/social playbooks under `marketing/`.
Node 20+, npm 10+. `package.json` declares version **1.8.1**.
## Architecture sketch
Monorepo-ish: one Astro app at the root with a sibling **standalone enrichment service**, plus content/marketing/video workspaces.
| Top-level dir | Role |
|-|-|
| `src/` | Astro app: `components/` (Astro + React), `pages/` (routes incl. `api/v1/*`), `lib/` (utilities, `features/` modules, `i18n/`, `shared/api/schemas/`), `layouts/`, `locales/` (de, en, es, fr, nl, pl, pt), `middleware*.ts` (auth + compression + coming-soon chain), `db/database.types.ts` (auto-generated from Supabase) |
| `supabase/` | `config.toml` + `migrations/` — schema source of truth. ~40 tables across 12 domains. |
| `services/data-enrichment/` | Standalone TS service: importers (cities, passports, seasonality, coordinates, costs, DN-visa, tax) → enrichers (Wikidata SPARQL, OpenRouter/Claude LLM, composite scores) → validators (z-score outliers, spot-check anchors, confidence). Has its own Dockerfile + package + tests. |
| `infra/k8s/{base,overlays}` | Kustomize K8s manifests; ArgoCD auto-syncs `develop` → staging, `main` → prod. |
| `argocd/` | ArgoCD application manifests. |
| `e2e/` | Playwright test suites. |
| `tests/` | Cross-cutting tests outside `src/`. |
| `docs/` | Starlight docs site (PRD, architecture, MVP plans, API). Built as `dist/client/docs/`. |
| `marketing/` | Strategy docs (SEO, social, ads, n8n automations, CRO audits). |
| `mcp-server/` | Project-local MCP server. |
| `video/` | Remotion compositions for hero / marketing videos. |
| `tools/` | `i18n-checker`, `lighthouse-mcp`. |
| `scripts/` | OG image generation, recalculation jobs, releases (`release.sh`), seeding, RAG/knowledge embedding. |
| `dev/` | `INDEX.md` — dev work index (avoid duplicating effort, find prior patterns). |
| `data/` | Reference data (incl. `cities.json`). |
| `.planning/`, `.windsurfrules`, `.cursor/` | Planning notes + IDE/AI rules. |
| `.claude/`, `.agents/` | Claude Code project setup — see below. |
| `.husky/`, `.github/` | Pre-commit hooks + CI workflows. |
**Build & run:**
- `npm run dev` (port 3000) — Astro dev. `npm run build` does app + Starlight docs + integrate. `npm run build:app` is app-only.
- `npm run ci` = lint + format:check + typecheck:full + build.
- Tests: `npm run test` (Vitest), `npm run test:e2e` (Playwright), `npm run test:acceptance` (Cucumber via tsx/esm), `npm run test:all` runs all three.
**Branch flow:** `feature/*` | `fix/*` → `develop` → `main`. **Never PR directly to `main`** — all PRs target `develop` (project rule, enforced in `CLAUDE.md`).
**Env tiers:** local (Supabase CLI + Docker) · staging (`stg.indepai.cloudfloo.io`, Supabase project `czaymkbhvjlrmyubmsnq`, branch `develop`) · prod (`indepai.app`, Supabase project `ufgxhkutjfymfetmguff`, branch `main`).
**Known gotchas (per `CLAUDE.md`):**
- `astro.config.mjs` has a Vite plugin stubbing `prom-client`, `ioredis`, `posthog-node` in client builds — add to `serverOnlyPackages` if a new Node-only dep leaks into React.
- `PUBLIC_*` env prefix = client-exposed. `SUPABASE_SERVICE_ROLE_KEY`, `STRIPE_SECRET_KEY` etc. must NEVER be `PUBLIC_*`.
- `src/db/database.types.ts` is auto-generated; regenerate with `npx supabase gen types typescript --local > src/db/database.types.ts` after migrations.
- Middleware chain: `middleware.ts` → `middleware-coming-soon.ts` → `middleware-compression.ts`. Coming-soon mode toggled via middleware, not feature flags.
## Claude/skills analysis
The repo is heavily Claude-Code-instrumented. Setup lives in `.claude/` with shared skills symlinked from `.agents/skills/`.
### Top-level Claude config
- `CLAUDE.md` (12 KB) — project rules: subagent discipline, no box-drawing tables, branch policy (PRs always to `develop`), key files, gotchas.
- `AGENTS.md` (2 KB) — short contributor guide: structure, commands, style, conventional commits.
- `.mcp.json` — MCP server bindings (Supabase, Playwright, Astro docs).
- `.claude/settings.json` — accept-edits mode, all-project-MCP enabled, hooks: `skill-activation-prompt.sh` on UserPromptSubmit, `pre-commit-check.sh` on Bash, post-tool-use tracker on edits, enhanced stop+build check.
- `.claude/hooks/` — TS-compiled hook scripts with their own `package.json` and `npm run check`.
- `.claude/skills/skill-rules.json` (28 KB) — auto-activation rules (keywords, intent patterns, file paths, content patterns; enforcement levels: block / suggest / warn).
- `.claude/skills/README.md` — onboarding doc for the skills system.
### Agents (subagent personas) — `.claude/agents/`
20 markdown subagent definitions, e.g.: `auth-route-debugger`, `auth-route-tester`, `auto-error-resolver`, `code-archeologist`, `code-architecture-reviewer`, `code-refactor-master`, `code-reviewer`, `customer-development`, `documentation-architect`, `frontend-error-fixer`, `marketing-director`, `plan-reviewer`, `premium-ux-designer`, `refactor-planner`, `team-configurator`, `tech-lead-orchestrator`, `ui-designer`, `ux-researcher`, `web-research-specialist`. One ready-built team in `.claude/teams/ux-research-squad/`.
### Slash commands — `.claude/commands/`
Project-specific: `analyze-user-journey`, `create-api-endpoint`, `debug-api-issue`, `deploy-feature`, `dev-docs(-update)`, `optimize-database`, `review-security`, `route-research-for-testing`, `view-implementation-plan`.
### Skills (project) — `.claude/skills/`
In-repo skills (each with a `SKILL.md`) — what they do, plain language:
- **backend-dev-guidelines** — house style for Astro 5 + Supabase backend: 2-layer architecture (routes → services), `withAuth` middleware, `ApiError`, Zod validation, rate limiting, logging. Auto-activates on backend code touches.
- **frontend-dev-guidelines** — Astro 5 file-based routing + React 19 islands + Tailwind 4 + shadcn/ui + custom hooks (`useMutation`, `useAsyncData`, `UserContext`) + Supabase wiring. Auto-activates on FE work.
- **infra-dev-guidelines** — K8s + Kustomize + ArgoCD + GH Actions + Docker + Supabase migrations playbook (HPA, ingress, env mgmt, security hardening).
- **database-dev-guidelines** — IndepAI's actual schema reference: 40 tables across 12 domains, RLS notes, deferred-vs-active table inventory, feature flags, enrichment pipeline. Activates on any DB-related task.
- **error-tracking** — enforces "ALL errors → Sentry v8" across services. Patterns for controllers, cron jobs, DB perf.
- **route-tester** — patterns for testing authenticated routes via cookie-based JWT (`scripts/test-auth-route.js`).
- **get-auth-token** — get a Supabase JWT (user/admin, CERT/local) for curl/manual auth testing.
- **chrome-devtools** — Chrome DevTools MCP usage; flags WSL/Windows requirement (`npx @dbalabka/chrome-wsl` first).
- **stitch-design** — Google Stitch MCP integration scoped to IndepAI's Stitch project (ID `1049283398874721291`, "IndepAI Dashboard Overview").
- **gemini-image-generator** — Nano Banana Pro / Gemini 3 Pro Image generation (text→image, image→image up to 14 refs, 1K/2K/4K).
- **generate-voiceover** — ElevenLabs voiceover pipeline for Remotion videos: reads `video/src/config.ts` timings, generates per-scene clips, ffmpeg-combines, optional Whisper verification.
- **marketing-analytics-advisor** — cross-platform Google Ads / GA / PostHog / Umami advisor, "patience-first" — blocks impulsive budget changes and validates traffic quality before optimisations.
- **skill-developer** — guide for writing/updating Claude skills + `skill-rules.json` (trigger types, enforcement levels, hooks, 500-line rule, progressive disclosure).
### Skills (shared) — `.agents/skills/` (symlinked into `.claude/skills/`)
Reusable bundles, mostly Stitch + Remotion + UI tooling:
- **enhance-prompt** — turns vague UI ideas into Stitch-optimized prompts (adds UI/UX keywords, design-system context).
- **design-md** — analyzes Stitch projects and writes a `DESIGN.md` semantic design system.
- **react-components** (`react:components`) — converts Stitch designs → modular Vite/React components with AST validation.
- **shadcn-ui** — discovery, install, customization, and best-practice patterns for shadcn/ui.
- **stitch-loop** — autonomous baton-passing loop pattern for iterative Stitch-driven site building.
- **remotion** — generates walkthrough videos from Stitch designs using Remotion (transitions, zooming, overlays).
- **remotion-best-practices** — domain knowledge for Remotion code (incl. `rules/subtitles.md` for captions).
- **dexploarer-threejs-scene-builder** — Three.js + R3F: scenes, characters/NPCs, procedural gen, animation retargeting, gameplay.
### Planning / IDE rules
- `.windsurfrules` — Codeium Windsurf rules.
- `.cursor/` — Cursor rules.
- `.planning/` — long-form planning docs.
## Documentation worth bookmarking (in repo)
- `docs/PRD.md` (v2.2, 2026-03-03) — canonical product spec.
- `docs/MVP-MASTER-PLAN.md` — current MVP plan (supersedes the older `MVP-CONCEPT-DESCRIPTION.md`).
- `docs/SCORING_SYSTEM.md` — FI-Score formulas.
- `docs/DATABASE-ARCHITECTURE.md` — DB design.
- `docs/SECURITY-COMPLIANCE-DESIGN.md` — GDPR + auth + RLS.
- `dev/INDEX.md` — running log of completed work, patterns, active tasks.
## Related
- [[Projects/cloudfloo/index]] — parent org
- [[About-Michal]] — owner profile (CloudFloo CEO/CTO)
---
Working clone: `~/.openclaw/agents/Dev/workspace/repos/indep-ai/` (not tracked in this vault).Tasks for this project · 0
— no tasks tagged with this project.