Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,7 @@ Staging E2E requires all three values together: `STAGING_SUPABASE_URL`, `STAGING

Open only what the task needs:

- [docs/architecture.md](docs/architecture.md): runtime boundaries, request flows, state, auth, billing, observability, PWA, and iOS.
- [docs/architecture.md](docs/architecture.md): runtime boundaries, request flows, state, auth, billing, observability, and PWA.
- [docs/development.md](docs/development.md): setup, environment behavior, worktrees, and common workflows.
- [docs/testing.md](docs/testing.md): what each gate proves, browser matrices, staging, artifacts, and cleanup.
- [docs/operations.md](docs/operations.md): CI, Vercel hosting, staging, deployment, rollback, and live verification.
Expand Down
5 changes: 2 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Live application: [debate.pi-stack.org](https://debate.pi-stack.org)
- **Practice.** Attack finds weak points. Ask is a streaming debate coach. Crossfire drills questioning. Sparring runs a timed round against the AI and scores it.
- **Library and History.** Sources and saved work, scoped to the Current Debate.
- **Account.** Google, email code, and demo-code sign-in; Basic and Pro plans through Stripe; sharing; admin announcements.
- **Platforms.** Web and installable PWA with an offline shell, plus a Capacitor iOS app.
- **Platforms.** Web and installable PWA with an offline shell.
- **Languages.** English, Spanish, and Hungarian interface and AI output.

Collaborative Workspace exists in the code but is hidden and on hold. Its routes appear only when `VITE_COLLABORATION_URL` is set.
Expand Down Expand Up @@ -53,7 +53,7 @@ npm run verify:full # adds the full desktop and mobile browser suite
## How it fits together

```text
Browser, PWA, or Capacitor iOS shell
Browser or PWA
-> React 18 + Vite client (Zustand stores, TanStack Query)
-> Supabase Auth, PostgreSQL with RLS, Edge Functions (Deno)
-> OpenRouter models, research providers, Stripe, Google APIs
Expand All @@ -79,7 +79,6 @@ supabase/ Edge Functions, migrations, pgTAP tests, local config
e2e/ Playwright browser, full-stack, live, staging, and canary tests
services/ Collaboration service for the hidden Workspace
public/ Static pages, PWA assets, and SEO files
ios/ Capacitor Xcode project
scripts/ Build, docs, SEO, and test helpers
.github/workflows/ Quality, live-provider, model-matrix, staging, and canary CI
.superset/ Worktree dev server, port allocation, and database gate
Expand Down
32 changes: 0 additions & 32 deletions capacitor.config.ts

This file was deleted.

4 changes: 2 additions & 2 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ Start with the smallest document that answers the task instead of loading every

## Understand the system

- [Architecture](architecture.md), current. Open before changing subsystem boundaries or tracing browser, Current Debate, data, AI, auth, billing, observability, PWA, or iOS flows.
- [Architecture](architecture.md), current. Open before changing subsystem boundaries or tracing browser, Current Debate, data, AI, auth, billing, observability, or PWA flows.
- [Agent guide](../AGENTS.md), current. Always-loaded commands, safety rules, and routing.
- [Root README](../README.md), current. Product overview and quick start.

Expand All @@ -21,7 +21,7 @@ Start with the smallest document that answers the task instead of loading every

## Set up and develop

- [Development guide](development.md), current. Open for installation, environment behavior, linked worktrees, frontend, backend, database, or iOS workflows.
- [Development guide](development.md), current. Open for installation, environment behavior, linked worktrees, frontend, backend, or database workflows.
- [Supabase backend](../supabase/README.md), current. Open before changing Edge Functions, shared backend modules, migrations, RLS, RPCs, or backend secrets.
- [Collaboration service](../services/collaboration/README.md), current. Only for the hidden Workspace.

Expand Down
12 changes: 3 additions & 9 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,18 +4,18 @@

## System context

DebateLab is a browser application with an optional Capacitor iOS shell. The client uses Supabase for sessions, persisted user data, database RPCs, and Edge Functions. Edge Functions keep privileged credentials server-side and integrate with AI providers, research services, Stripe, and Google APIs.
DebateLab is a browser application. The client uses Supabase for sessions, persisted user data, database RPCs, and Edge Functions. Edge Functions keep privileged credentials server-side and integrate with AI providers, research services, Stripe, and Google APIs.

```text
Browser or Capacitor
Browser or PWA
-> React routes, feature components, stores
-> Supabase Auth, PostgreSQL, RPCs, Edge Functions
-> AI providers, research, Stripe, Google Docs
```

## Client startup and routing

[`src/bootstrap.ts`](../src/bootstrap.ts) imports the application entry immediately, then schedules Jam after window load and idle time. [`src/main.tsx`](../src/main.tsx) mounts the application before starting native runtime handling, observability, native URL handling, and service-worker registration. Vercel browser telemetry is disabled inside the native shell and loaded behind a separate Suspense boundary.
[`src/bootstrap.ts`](../src/bootstrap.ts) imports the application entry immediately, then schedules Jam after window load and idle time. [`src/main.tsx`](../src/main.tsx) mounts the application before starting observability and service-worker registration. Vercel browser telemetry is loaded behind a separate Suspense boundary.

[`src/App.tsx`](../src/App.tsx) owns routes and top-level providers. Pages are lazy loaded. Public routes cover marketing, legal pages, login, sources, and shared content. `/app/*` routes pass through `RequireAuth` and include the main tools, the Current Debate dashboard (`/app/debate`), history, library, timer, sparring, flowchart, settings, and administration. The header holds only Home, the Current debate menu, Library, History, and the language, theme, and Settings controls; tools are launched from Home and the dashboard.

Expand Down Expand Up @@ -138,12 +138,6 @@ CI and staging must not upload authenticated browser captures. Logging must not

The service worker and manifest provide installable web assets and an offline app shell. It precaches only the navigation shell and static identity assets; route chunks enter the runtime cache when a user visits them. On first registration, the client also reports same-origin `/assets/` resources that loaded before the worker took control so the first visited route works offline without a forced reload. Updates wait for the normal service-worker lifecycle instead of reloading an active page. Offline support does not make unvisited routes, authenticated Supabase, or AI operations available without a network.

## iOS shell

[`capacitor.config.ts`](../capacitor.config.ts) owns the native app identifier, build directory, schemes, and native plugin settings. The iOS app wraps the same Vite output using a relative asset base.

OAuth still travels through the provider and Supabase HTTPS callback before returning to the app callback scheme. Native URL handling lives in the client startup path.

## Deployment boundary

Vercel builds `dist/` with Node 22 and serves it. [`vercel.json`](../vercel.json) owns SPA fallback, cache policy, crawler restrictions, and response security headers. Merging to `main` deploys the frontend to production; Supabase migrations and Edge Functions deploy separately. GitHub workflow files own quality, live-provider, staging, and canary automation.
Expand Down
12 changes: 0 additions & 12 deletions docs/development.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,6 @@ Never overwrite unrelated changes. Do not switch to the primary checkout because
- Deno 2.x for Edge Function tests
- Docker and Supabase CLI 2.115 or newer for database work
- Playwright browser binaries for browser gates
- Xcode and CocoaPods or Swift Package Manager support for native iOS work

Install the locked JavaScript tree with the Node version from `.nvmrc`:

Expand Down Expand Up @@ -152,17 +151,6 @@ Read [testing.md](testing.md) before running WebKit or staging.

Agentic tests (`agentic/*.e2e.ts`, the e2e runner) drive the verification stack, never a dev server you started. Run them with `.claude/skills/verify-debatelab/bin/verify.sh e2e run` after `verify.sh up`. See [testing.md](testing.md#agentic-browser-tests).

## iOS workflow

```bash
npm run ios:build
npm run ios:open
```

The Capacitor build uses a relative Vite base and syncs `dist/` into the native project. [`capacitor.config.ts`](../capacitor.config.ts) owns the app ID, app name, schemes, and native settings.

Do not hand-edit generated package documentation. Make native configuration changes through Capacitor or Xcode as appropriate.

## Documentation workflow

Run:
Expand Down
3 changes: 1 addition & 2 deletions docs/operations.md
Original file line number Diff line number Diff line change
Expand Up @@ -154,7 +154,7 @@ Current functions mostly use local explicit origin allowlists. The exact list ca

Before enabling protected browser staging, verify `http://127.0.0.1:18080` for `demo-code-login`, `ai`, `ai-stream`, `admin`, and `announcements`. Do not broaden origins to `*` merely to make a test pass.

Native requests may use `capacitor://localhost`. Local development origins must remain bounded to intended ports and hosts.
Local development origins must remain bounded to intended ports and hosts.

## Secrets

Expand Down Expand Up @@ -206,6 +206,5 @@ Do not expose protected data in artifacts. Record the commit, environment, opera
- New frontend errors against Supabase right after a merge: the matching migration or function may not be applied to production yet. Run `npm run backend:status` from the linked checkout.
- Function returns unauthorized after deploy: check handler auth and environment propagation before changing gateway settings.
- Browser works on one route only: check the `vercel.json` SPA rewrite and cache headers.
- Native callback fails while web works: check Capacitor scheme and Supabase redirect allowlist.

Read [testing.md](testing.md) for evidence rules and [`../supabase/README.md`](../supabase/README.md) for backend ownership.
2 changes: 1 addition & 1 deletion eslint.config.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import reactRefresh from "eslint-plugin-react-refresh";
import tseslint from "typescript-eslint";

export default tseslint.config(
{ ignores: ["dist", "coverage", "ios/App/App/public", ".remember"] },
{ ignores: ["dist", "coverage", ".remember"] },
{
extends: [js.configs.recommended, ...tseslint.configs.recommended],
files: ["**/*.{ts,tsx}"],
Expand Down
13 changes: 0 additions & 13 deletions ios/.gitignore

This file was deleted.

Loading
Loading