# JÁ² Backoffice — dokumentace

> Pro **AI agenta**: začni [`00-start-here.md`](./00-start-here.md), pak [`AGENTS.md`](../../AGENTS.md) v rootu.
> Pro **lidský dev**: pojď přes [`architecture/overview.md`](./architecture/overview.md).

## 1. Big picture

JÁ² Backoffice je **interní tool pro JÁ² tým** (David, Honza, Eva, Petra, Martin):
- **CRM** — customers, happenings, check-in, FAPI / SmartEmailing / AffilBox / Quiz pages integrace
- **Support inbox** — Gmail-backed unified tickets, AI drafts
- **Admin** — uživatele + role + permissions, happenings settings, voucher mappings, brigádníci přístup
- **Skills knihovna** — sdílené AI skill prompty pro internal agenty

Sister projekt = `ja2-akademie` (user-facing platforma, doména `app.ja2.academy`).

> **Post-split (od 19.5.2026):** `ja2-backoffice` je standalone repo, vlastní Supabase project (`cjnxgslqotzumajkwozy`), vlastní deploy. Sister `ja2-akademie` má vlastní repo, vlastní Supabase. Integration = 1 read HTTP endpoint `/api/akademie/customer-context`.

## 2. Mapa dokumentace

### Začni tady

| Dokument | Pro koho | Co najdeš |
|---|---|---|
| [`00-start-here.md`](./00-start-here.md) | **Start** | 5-min onboarding pro nového dev / agenta |
| [`AGENTS.md`](../../AGENTS.md) (root) | Agent | High-level pravidla a doc map |
| [`CLAUDE.md`](../../CLAUDE.md) (root) | Agent | Strategický směr + hard pravidla |

### Architektura (`architecture/`)

| Dokument | Co najdeš |
|---|---|
| [`overview.md`](./architecture/overview.md) | High-level architektura, vrstvy, kde co žije |
| [`post-split-topology.md`](./architecture/post-split-topology.md) | Proč 2 repa, jak komunikují |
| [`data-flow.md`](./architecture/data-flow.md) | Request lifecycle (auth → CRM → support → integrations) |
| [`tech-stack.md`](./architecture/tech-stack.md) | Proč Next 15 / Supabase / Anthropic / Gmail API / FAPI / AffilBox |

### Features (`features/`)

| Dokument | Co najdeš |
|---|---|
| [`auth.md`](./features/auth.md) | Google OAuth, magic link, password reset, RBAC modules |
| [`crm.md`](./features/crm.md) | Customers, identities, entitlements, attributions, goals, quiz |
| [`checkin.md`](./features/checkin.md) | QR scanner, multi-device sync, undo, per-type stats |
| [`support.md`](./features/support.md) | Gmail OAuth + Pub/Sub, conversations, AI drafts |
| [`integrations.md`](./features/integrations.md) | FAPI invoices, AffilBox, SmartEmailing, Gmail, Quiz |
| [`mcp.md`](./features/mcp.md) | MCP server, 7 admin modulů, role gates |
| [`ai-drafts.md`](./features/ai-drafts.md) | Anthropic SDK, style profile learning, weekly rebuild cron |
| [`happenings.md`](./features/happenings.md) | Multi-event abstrakce, products, team roles |
| [`multi-event.md`](./features/multi-event.md) | Per-event isolation, feature flags |
| [`registrations.md`](./features/registrations.md) | Per-event signup, attendee types, arrival tracking |
| [`modules.md`](./features/modules.md) | Module-scoped RBAC permissions |
| [`admin.md`](./features/admin.md) | Admin panel guide |

### Reference (`reference/`)

| Dokument | Co najdeš |
|---|---|
| [`env-vars.md`](./reference/env-vars.md) | Kompletní env reference |
| [`api-routes.md`](./reference/api-routes.md) | Všech 27 endpointů — method, auth, payload, response |
| [`db-schema.md`](./reference/db-schema.md) | 44 migrací, tabulky, RLS |
| [`mcp-tools.md`](./reference/mcp-tools.md) | 7 modulů, ~30 tools, role gates |
| [`akademie-integration.md`](./reference/akademie-integration.md) | `/api/akademie/customer-context` contract (server-side) |

### Ops (`ops/`)

| Dokument | Co najdeš |
|---|---|
| [`deployment.md`](./ops/deployment.md) | Replit Autoscale, custom doména, secrets, smoke test |
| [`deploy-workflow.md`](./ops/deploy-workflow.md) | **Deploy + rollback runbook** (ticket → branch → PR → merge → live) — pro human i agent |
| [`runbook-cutover.md`](./ops/runbook-cutover.md) | Phase B.PRE cutover playbook (legacy DB → new Supabase) |
| [`migration-from-monorepo.md`](./ops/migration-from-monorepo.md) | Jednorázový split runbook (archivní) |
| [`troubleshooting.md`](./ops/troubleshooting.md) | Gmail OAuth, FAPI sync, magic link, build issues |
| [`secrets-rotation.md`](./ops/secrets-rotation.md) | Gmail / FAPI / AffilBox / AKADEMIE_INTEGRATION_TOKEN rotation |
| [`pre-event-checklist.md`](./ops/pre-event-checklist.md) | JÁ² ŽIVĚ Brno 30.-31.5.2026 dry-run |
| [`pm-workflow.md`](./ops/pm-workflow.md) | **Linear + Claude Code ticket workflow** (PM systém) |
| [`conventions.md`](./ops/conventions.md) | Code style + naming |

### Strategy (`strategy/`)

| Dokument | Co najdeš |
|---|---|
| [`product-vision.md`](./strategy/product-vision.md) | Backoffice scope, vztah k akademie, post-launch směr |
| [`agent-operating-instructions.md`](./strategy/agent-operating-instructions.md) | Bootstrap prompt pro Team Agent |
| [`agent-bootstrap-prompt.md`](./strategy/agent-bootstrap-prompt.md) | Initial config pro AI agenta přes MCP |
| [`roadmap.md`](./strategy/roadmap.md) | Fáze pre/post launch |

### Audits (`audits/`)

| Dokument | Co najdeš |
|---|---|
| [`README.md`](./audits/README.md) | Pravidla pro audit reporty |
| [`auth-stack-audit-2026-05.md`](./audits/auth-stack-audit-2026-05.md) | Auth/email/token audit |
| [`post-split-audit-2026-05.md`](./audits/post-split-audit-2026-05.md) | Verifikace splitu vs monorepo |

## 3. Klíčové konvence

- **TypeScript strict** + Tailwind 4 (`@theme` direktive)
- **Server actions** s `"use server"` direktivou
- **Supabase RLS + service-role pattern** (klient používá user auth, server používá service role pro privilegované operace)
- **Sanitized error responses** (žádné raw error.message do UI bez review)
- **Email provider abstrakce:** `sendTransactional()` API → swap-friendly (SmartEmailing → budoucí Brevo = jen reimplementace, callsites se nemění)

## 4. Bezpečnost

- Service role klíč **pouze server-side** (`SUPABASE_SERVICE_ROLE_KEY`)
- API tokeny: SHA-256 hash v DB, plain text **pouze 1×** při generování
- Auth emaily přes **SmartEmailing** (sender `ja2@davidkirs.cz`, **NIKDY** `noreply@`)
- RLS na všech user-vlastněných tabulkách — viz [`reference/db-schema.md`](./reference/db-schema.md)
- Sanitized error responses (žádný raw `error.message` do UI bez review)
- Detail: [`features/auth.md`](./features/auth.md), [`audits/auth-stack-audit-2026-05.md`](./audits/auth-stack-audit-2026-05.md)

## 5. Stav projektu (k 19.5.2026)

**Hotové:**
- ✅ Split z monorepa `ja2_academy_platform/apps/web` → standalone repo
- ✅ Nový Supabase project `cjnxgslqotzumajkwozy` (43 migrací aplikováno)
- ✅ Cutover dat z legacy `ja2_academy` (512 řádků: 67 customers, 51 registrations, 81 entitlements, ...)
- ✅ Phase B.0 auth fixy: `/auth/callback` page+handler, silent email failures logged, `noreply@` removed, `/api/akademie/*` public route restored
- ✅ Audit reports

**Probíhající (pre-launch):**
- ⏳ Update Replit Secrets pro nový Supabase + Republish
- ⏳ Smoke test: magic link + Google login + CRM views
- ⏳ Smaž legacy `ja2_academy` Supabase project

**Akce u Davida:**
- 🔴 Supabase Dashboard → Auth → Providers → Google → Authorized Client IDs (pravděpodobně stejný "Unacceptable audience" bug jako akademie)

**TODO (post-launch):**
- Test coverage pro auth + MCP routes
- Sentry / observability
- Rate-limit migrace na Supabase-backed table
- Pre-event checklist dry-run pro JÁ² ŽIVĚ Brno 30.5.

## 6. Změny 13.5.2026 (Context Store removal — historie)

Backoffice **Context Store byl kompletně odstraněn** ze user-facing app (žije v akademii Studio):
- ❌ `/store` route, `/api/export`, `/api/webhook/github-sync`, `/settings/github` — smazány
- ❌ 5 MCP tools (`list_files`, `read_file`, `write_file`, `delete_file`, `search_files`)
- ❌ `lib/store/`, `lib/github/`, `components/store/`
- ✅ Auto-migrace dat do akademie `user_context_files(scope='workspace')` proběhla
- ✅ Backoffice MCP je nyní pure-admin: CRM, support, check-in, integrace, skills knihovna

## 7. Kde se píší změny

Vždy průběžně aktualizuj:
1. **`src/docs/CHANGELOG.md`** — co se přidalo / změnilo / smazalo
2. **Konkrétní `.md` v adresáři** podle scope změny
3. **`AGENTS.md`** (root) — pokud se mění high-level pravidla pro agenty

## 8. Naming convention pro nové docs

- `features/<feature-name>.md` — per-feature deep dive
- `reference/<topic>.md` — auto-generovaný / faktologický seznam
- `architecture/<aspect>.md` — system design / cross-cutting
- `ops/<runbook>.md` — operational playbook
- `strategy/<topic>.md` — strategický směr / vision
- `audits/<scope>-audit-YYYY-MM.md` — point-in-time review