JA2 DocsPřihlásit se

JÁ² Backoffice — dokumentace

Pro AI agenta: začni 00-start-here.md, pak AGENTS.md v rootu. Pro lidský dev: pojď přes 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 | Start | 5-min onboarding pro nového dev / agenta | | AGENTS.md (root) | Agent | High-level pravidla a doc map | | CLAUDE.md (root) | Agent | Strategický směr + hard pravidla |

Architektura (architecture/)

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

Features (features/)

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

Reference (reference/)

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

Ops (ops/)

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

Strategy (strategy/)

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

Audits (audits/)

| Dokument | Co najdeš | |---|---| | README.md | Pravidla pro audit reporty | | auth-stack-audit-2026-05.md | Auth/email/token audit | | 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
  • Sanitized error responses (žádný raw error.message do UI bez review)
  • Detail: features/auth.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