Kile AI — Implementation Charter (Stage 0)
Product: Kile AI, a premium, affordable, multi-model AI assistant SaaS by ASSIGNMENT AMIGO LTD. Domains: www.kileai.com (marketing), www.kileai.com/c (workspace).
Status legend: ✅ Done · 🟡 In progress / partial · ⛔ Blocked (external action needed) · ⬜ Not started
1. Charter
| Item | Decision |
|---|
| Frontend | React 19 + TypeScript + Tailwind v4 + shadcn/ui (TanStack Start), maintained in Lovable + GitHub sync |
| Data/Auth | Externally owned Supabase project (Postgres, Auth, Storage, Realtime, pgvector, Queues) |
| Orchestration | Independent, versioned AI API (/v1) — Rust/Axum preferred |
| Workers | Isolated Python/SymPy math worker; GPU workers for media (later) |
| LLM gateway | OpenRouter, behind a replaceable provider-adapter interface |
| Payments | Stripe subscriptions (not active) |
| Release 1 | Web app, chat, auth, model routing, quotas, math foundation, voice dictation, spoken responses |
| Later | Full agents, RAG, advanced math, image/video generation, realtime voice |
2. Architecture
flowchart LR
U[Browser: Kile web app] -->|Supabase JWT| SB[(Supabase: Auth / Postgres+RLS / Storage / Realtime / pgvector)]
U -->|JWT, SSE stream| API[Kile Orchestration API v1 - Rust/Axum]
API -->|verify JWT, service role server-side only| SB
API --> RT[Router: capability + quota + cost]
RT --> OR[OpenRouter adapter]
RT --> STT[STT/TTS adapters]
API --> Q[Queues] --> MW[Python SymPy math worker]
Q --> GW[GPU media workers - later]
API --> ST[Stripe] -->|webhooks| API
API --> AUD[(Audit log + usage ledger)]
3. Security boundary map
| Zone | Trust | Holds secrets? | Rules |
|---|
| Browser | Untrusted | Publishable key only | No provider/service-role/Stripe secrets; UI counters are display-only |
| Supabase (RLS) | Data authority | — | RLS on every exposed user table; no broad public policies; no unrestricted SECURITY DEFINER |
| Orchestration API | Trusted | OpenRouter, service role, Stripe secret | Verifies JWT; atomic quota reservation; cost ceilings; idempotency keys |
| Workers | Isolated | Minimal | Sandboxed, no inbound internet, time/memory limits |
| Stripe webhooks | External | Signing secret | Signature verified; idempotent event processing |
4. API contract plan (v1, draft)
| Method | Path | Purpose | Status |
|---|
| POST | /v1/chat/completions | Streamed (SSE) chat with routing | ⬜ |
| GET | /v1/models | Eligible models for caller + plan | ⬜ |
| POST | /v1/quota/reserve · /commit · /release | Atomic quota lifecycle | ⬜ |
| POST | /v1/math/solve | SymPy-verified solving | ⬜ |
| POST | /v1/voice/transcribe · /v1/voice/speak | STT / TTS | ⬜ |
| GET | /v1/usage | Provider-reported usage (estimates flagged) | ⬜ |
| POST | /v1/billing/checkout · /webhooks/stripe | Subscriptions | ⛔ awaiting Stripe |
Streaming events: message.start, delta (grapheme-safe text), tool.result, usage (input/output/cached/reasoning tokens, estimated: bool), error, done.
5. Data ownership policy
- Every row of user content (conversations, messages, files, recordings, generated artifacts) carries
owner_id and is RLS-scoped to it.
- Users can delete any conversation, file, recording or artifact; deletion cascades to Storage objects and vector embeddings.
- Usage ledger and audit logs are append-only, retained for billing/legal periods, readable by owner (own rows) and admins only.
- Roles live in a separate
user_roles table, never on profiles.
6. Prioritized backlog (Release 1)
| # | Item | Depends on | Status |
|---|
| 1 | Brand system, landing page, favicon | — | ✅ |
| 2 | Typewriter/streaming reveal component (demo only) | 1 | 🟡 scripted demo only |
| 3 | Connect external Supabase project | User action | ✅ connected; hosted email enabled, signup enabled, email confirmation required |
| 4 | Auth (email + Google) | 3 | 🟡 email signup/signin/signout/recovery and profile editing implemented; authenticated checks unavailable on external unmanaged project; Google pending |
| 5 | Schema: profiles, user_roles, conversations, messages, usage_ledger, audit_log | 3 | 🟡 private tables and spending/request records applied; roles not needed or implemented yet |
| 6 | Orchestration API skeleton + OpenRouter adapter | Hosting decision, OpenRouter key | ⛔ secured connector verified HTTP 200; Rust source and deployment instructions prepared; external deployment pending |
| 7 | Live chat with SSE streaming | 4, 6 | ⛔ private conversation URLs and streaming UI/relay prepared; actual inference and two-thread readback not verified; controls disabled pending setup |
| 8 | Router + quotas (atomic reservations) | 5, 6 | 🟡 service-only reservation/settlement functions; account spending disabled; allowances, concurrency integration checks, routing and production reconciliation pending |
| 9 | Math foundation (SymPy worker) | 6, worker hosting | ⛔ |
| 10 | Voice dictation + spoken responses | 6, STT/TTS provider | ⬜ |
| 11 | Usage dashboard (K/M token formatting) | 8 | ⬜ |
| 12 | Stripe subscriptions | Stripe account, final prices | ⛔ |
7. Feature dependency map
flowchart TD
SB[Supabase] --> Auth --> Chat
API[Orchestration API] --> Chat
API --> Router --> Quotas --> Usage
Quotas --> Billing
API --> Math
API --> Voice
Chat --> Agents & RAG
API --> Media[Images / Video]
8. Requirements traceability
The original SRS defining FR-001 – FR-188 and the media-generation requirements is not present in this project. Identifiers must not be invented.
| Gap ID | Gap | Action |
|---|
| GAP-01 | SRS FR-001–FR-188 text missing | Please upload the SRS; matrix will be populated from it |
| GAP-02 | Media-generation FR identifiers missing | Supply numbering |
| GAP-03 | Final plan prices & allowances | Business decision |
| GAP-04 | Contact email for footer | Supply address |
Proposed additions (not confirmed): PA-01 typewriter reveal + reduced-motion; PA-02 quota-aware model continuation; PA-03 per-artifact deletion controls.
9. Environment matrix
| Development | Staging | Production |
|---|
| Frontend | Lovable preview | Lovable preview (branch) | kileai.com |
| Supabase | Dev project | Staging project | Prod project |
| API | Local / dev host | Staging host | Prod host |
| Stripe | Test mode | Test mode | Live mode (approval required) |
| OpenRouter | Low-limit key | Capped key | Prod key + spend cap |
10. Risk register
| Risk | Impact | Mitigation |
|---|
| Provider price/availability changes | High | Adapter layer, live price sync, fallback models |
| Quota race conditions / overspend | High | Atomic DB reservations, hard cost ceilings |
| Secret leakage to browser | Critical | Secrets only in API; CI secret scanning |
| Long jobs in edge functions | Medium | Queue + dedicated workers |
| Missing SRS → scope drift | Medium | Gap register; no invented FR IDs |
11. Release gates (measurable)
- Typecheck, lint and build pass; automated tests ≥ 80% on quota/billing logic.
- RLS enabled on 100% of exposed tables; security scan shows no critical findings.
- p95 time-to-first-token < 2.5 s on staging.
- 0 secrets in client bundle (verified by scan).
- Quota tests prove no overspend under 50 concurrent requests.
- Accessibility: keyboard-navigable, WCAG AA contrast, reduced-motion honoured.
12. Definition of done
A feature is done only when: it works end-to-end against real services, has automated tests, enforces authorization server-side, labels any estimate, passes the release gates, and is documented in this charter's status table.
13. Required external setup (user actions)
- External Supabase connected; verify email Auth configuration and redirect URLs during implementation.
- OpenRouter securely connected; server calls must use the linked connector credentials, never browser credentials.
- Choose hosting for the Rust API and Python worker.
- Stripe account exists; payment integration and final prices remain pending (later).
- Upload the SRS (FR-001 – FR-188).
14. Next-stage evidence and inventory (9 November 2026)
- Browser verified:
/c redirects signed-out users to sign-in; signup and recovery forms render; missing recovery link is rejected; home scripted preview remains functional; mobile sign-in has no horizontal overflow; no browser runtime errors; unauthenticated chat returns 401.
- Automated: six frontend tests passed (routing, graphemes, fragmented Unicode SSE, CRLF, interrupted stream, safe return paths); three Rust cost-bound unit tests passed. Preview harness reports build OK. New account/chat files lint with no errors and one refresh warning. Full-project lint fails on older formatting errors (469 errors, 15 warnings); not claimed passing.
- Hosted Auth settings checked by read-only request: email enabled, signup allowed, auto-confirm off. Actual signup/email delivery, login, owner readback, two-conversation persistence and sign-out are not verified: managed authenticated testing is unavailable for this external project.
- Schema inventory: profiles, conversations, messages, spending_accounts, usage_ledger, ai_requests, audit_log; signup/timestamp triggers; service-only
kile_reserve and kile_finish. Three migrations applied, including revocation of inherited anonymous and excess authenticated grants. All new tables have RLS; verify ownership through real account tests before production.
- App inventory: public auth/recovery pages; protected
/c, /c/$threadId, /account; workspace functions; authenticated /api/chat and /api/chat/cancel; AI Elements controls; transcript stream parser and tests.
- External inventory:
services/orchestrator includes Rust source, Cargo lock, Dockerfile, cost-bound tests, API contract and setup/rollback instructions. No generated Rust binaries are kept in the project.
- Existing security findings: two pre-existing execute-permission warnings on a security-definer function; unrelated to these migrations and not resolved in this stage. Full security scan and production gates remain pending.
- Open blockers: external HTTPS AI host (
KILE_API_URL), approved model/output budget and provider price ceilings, account spending allowances, external credential provisioning, authenticated integration tests and recovery redirect configuration. No paid inference or payments activated.