sase.tr/PROJECT_INDEX.md

# Project Index: sase.tr (sase-v2)

Generated: 2026-06-10 · regenerate via `/sc:index-repo` · machine-readable twin: `PROJECT_INDEX.json`

Turkish B2B SaaS: VIN decode + OEM parts-catalog platform for parts dealers & repair shops.
pnpm 10.29.3 workspaces + Turbo · Node 22 · TypeScript · Biome.

## Structure

```
apps/api          NestJS 10 backend — REST API (:4000) + separate BullMQ worker
apps/web          React 19 + TanStack Router/Query + Vite SPA (Remotion video, i18n)
packages/shared   @sase/shared — zod schemas, types, constants (plans, error-codes), utils (vin-validator, formatters)
packages/config   @sase/config — shared config
packages/ui       @sase/ui — shadcn-style components
scripts/          one-off ops/debug (emex scrapers, backfills, deploy.sh, pl24-catalog-explorer)
qa/post-deploy    post-deploy smoke checks
docs/             internal docs — see docs/INDEX.md (testing, design-specs, pl24-catalog, product)
docker/           local dev compose (minio, nginx)
```

## Entry Points

- `apps/api/src/main.ts` — API bootstrap (also serves built web via ServeStatic; no nginx in prod)
- `apps/api/src/worker.ts` — BullMQ worker process (separate container)
- `apps/api/src/database/migrate.ts` — custom SHA256-tracked migration runner over `apps/api/drizzle/` (14 SQL migrations + `meta/_journal.json`)
- `apps/web/src/main.tsx` — SPA bootstrap (`routeTree.gen.ts` generated by `tsr generate`)

## API Modules (`apps/api/src/`)

- **vehicles/** — VIN decode orchestration; fallback chain Corgi → PartsCatalogs → PL24 → EMEX → NHTSA; slim decode response + Redis candidate stash (`vin-cache-keys.ts`)
- **integrations/pl24/** — PartsLink24: shared P4 core + per-brand services (`psa`, `volvo`, `ford`, `hyundai-kia`, `opel`, `ford-legacy`) + `parsers/`
- **integrations/emex/** — emexdwc.ae scrape: HTTP via undici ProxyAgent, Playwright fallback (`emex.browser.ts`), tree parser
- **integrations/parts-catalogs/** — PartsCatalogs API ("pcat")
- **integrations/p/** — OEM cross-reference ("P", TecDoc-derived MySQL db; `P_DB_*` env)
- **integrations/corgi/**, **vin-api/** — offline WMI lookup; NHTSA fallback
- **integrations/catalog-source-db/** — upstream source-DB bridge
- **catalog/** — catalog browse endpoints (`catalog`, `pcat-catalog`, `emex-catalog` controllers/services)
- **categories/**, **parts/**, **brands/** — category tree (partCount rollup, lazy drill/heal), parts, brand canonicalization
- **auth/** (better-auth cookie sessions), **users/**, **referrals/**
- **payments/** (Stripe), **subscriptions/**, **plans/**
- **jobs/** — BullMQ queues + processors: `catalog-prefetch`, `emex-scrape`, `translation`, `lifecycle-email`, `subscription-expiry`, `query-cleanup`
- **posthog/** — server-side flag eval + `kill-source-*` switches · **meta-capi/** — Meta Conversions API
- **notifications/** (Novu), **email/** (Postal), **chatwoot/**
- **analytics/**, **telemetry/** (OTel → OTLP), **common/** (incl. catalog-degradation → Sentry), **redis/**, **storage/** (S3/MinIO), **translations/** (OpenAI), **admin/**, **internal-admin/**, **blog/**, **changelog/**, **demo/**, **contact/**
- **config/** — `env.validation.ts` zod gate (beware `""` vs undefined), `configuration.ts`
- **database/** — Drizzle provider + `schema/` split: `core`, `pl24`, `emex`, `parts-catalogs`, `relations`

## Web (`apps/web/src/`)

- **routes/** — public: `index`, `pricing`, `blog`, `demo`, `about/contact/kvkk/privacy/terms` · `_auth/`: login, register, forgot/reset password, email-verified · `dashboard/`: `search` (main VIN flow), `vehicles_/$id[/categories_/$categoryId]`, catalog trees (`catalog_/$brandName/...`, `catalog_/pcat/...`, `catalog_/emex/...`), `oem.$code` (cross-ref), `subscription`, `billing`, `history`, `settings`, `service-test` (admin), `admin/*` (users, analytics, referrals, copy-logs)
- **lib/** — `api-client`, `auth-client`, `posthog`, `surveys` (API-mode survey renderer), `meta-pixel`, `faro`, `sentry`, `chatwoot`, `i18n`, `vehicle`
- **stores/** (zustand), **components/**, **remotion/**, **messages/** (i18n), **hooks/**

## Configuration

- `turbo.json`, `biome.json`, `tsconfig.json` — build/lint/typecheck pipeline
- `docker-compose.coolify.yml` — prod/staging: `api` + `worker` + `sase-redis` (Coolify env reaches a service ONLY if its `environment:` block references `${VAR}`)
- `Dockerfile` — multi-stage node:22-alpine + Chromium (runtime imports MUST be in `dependencies`)
- `ecosystem.config.js` — PM2 config

## Tests

- API: 30 `*.spec.ts` (Vitest) → `pnpm --filter api test`
- Web: 24 `*.test.ts(x)` (Vitest only; **no Playwright e2e**) → `pnpm --filter web test`; plus per-package `index.spec.ts`
- `qa/post-deploy/` smoke checks

## Key Dependencies

NestJS 10 · drizzle-orm 0.41 + postgres · better-auth · bullmq + ioredis · stripe · posthog-node · openai (translations) · undici (proxied fetch — global fetch lacks `dispatcher`) · Sentry + OpenTelemetry · mysql2 (P/TecDoc) ·· React 19 · TanStack Router/Query · zustand · posthog-js · @grafana/faro · remotion · zod throughout.

## Quick Start

1. `pnpm install`
2. `pnpm dev` (turbo: api :4000 + web :3000)
3. `pnpm lint` / `pnpm typecheck` / `pnpm test`
4. DB: `pnpm --filter api db:migrate` (custom runner) · `db:studio` · `db:seed`

## Deployment (Coolify — NEVER edit on server)

- Push `dev` → auto-deploys staging **dev.sase.tr** — verify every change here first
- Merge to `main` → auto-deploys prod **sase.tr** (only after dev verified)

## Docs Map

- `CLAUDE.md` / `AGENTS.md` — assistant instructions · `docs/INDEX.md` — internal docs index
- Root reports: `upstream-prob.md`, `undecoded-vin-rca.md`, `posthog-max-leverage.md`, `posthog-feature-roadmap.md`, `katalogayapi.md`, `knowledge.md`, `ralpRapor.md`, `emex-hierarchy-plan.md`, `MANIFEST*.md`, `RECOVERY-FN-412.md`, `SCOPING-FN-411.md`, `SASE_PRD_Hesap_Paylasimi_Onleme_v1.1.md`
- Business/ops workspace knowledge base: `/home/s/ss/INDEX.md`