PlugOne is the platform at plugone.us. It hosts the Business Visibility Center (BVC) — an operator console for managing business identity, visibility, and verifiable facts.

Core concepts

• Entity — a business under PlugOne control (slug + display name + status).
• Dossier — the per-entity page (codex entries + history).
• Codex entry — a versioned fact about an entity (key + JSON value).
• Command — every state-changing action; runs through a single server pipeline and is logged.
• Command log — append-only audit of every command attempt (success or failure).
• Roles — admin, moderator (operator), viewer. First signup auto-promoted to admin.
• QR / registry — public dossier surface (Phase 2; the dossier slug is the route key).
• PlugStack shell — the BVC chrome at /bvc with left-nav modules.

Public vs private surfaces

• Public: /, /help, /operators-manual.
• Auth-required: /bvc, /bvc/entities, /bvc/entities/$id, /bvc/commands, /admin, /dashboard.
• Anonymous: /auth (signup, sign-in, reset).

All /bvc/* routes use a beforeLoad gate that redirects to /auth?redirect=<path> if no session.

entities

One row per business under management.

RLS: SELECT/INSERT/UPDATE allowed for admin or operator. DELETE not allowed.

codex_entries

Versioned facts about an entity. New entry for the same key supersedes the previous one.

RLS: SELECT/INSERT for admin or operator. UPDATE/DELETE not allowed (versioning by insert).

command_log

Append-only audit of every command pipeline call.

RLS: SELECT admin only. Inserts done by service role from server fn.

profiles

RLS: SELECT/UPDATE own row; admin reads all.

user_roles

RLS: read own; admin manages all. Used by has_role(uid, role) security-definer function in every other table's policies.

Example rows

entities:
  { id: "...", slug: "thedonuthouse", display_name: "The Donut House", status: "active" }

codex_entries:
  { entity_id: "...", key: "address", value: {"street":"123 Main"}, version: 1 }
  { entity_id: "...", key: "address", value: {"street":"456 Oak"}, version: 2, superseded_by: null }

command_log:
  { command: "entity.create", payload: {slug:"x"}, result: {id:"..."}, ok: true }

Flows

• Signup: /auth → email + password → trigger handle_new_user creates profile + role (admin if first user, viewer otherwise) → session returned (auto-confirm on) → redirect to /bvc/entities or ?redirect.
• Sign in: email + password → session → redirect.
• Reset: /auth (Forgot password) → email link to /auth → new password.
• Email confirmation: Currently auto-confirm = true. Disable in Cloud → Auth → Email if you want manual verification (requires SMTP).
• Session persistence: localStorage via Supabase browser client; restored on every page load.
• Redirect logic: /auth accepts ?redirect=/safe/path; only relative paths allowed.

Recovering a locked-out admin

1. Try password reset at /auth (Forgot password).
2. If the reset email never arrives, open Cloud → Auth → Users, find the user, click "Send password recovery".
3. If the role row is missing, run a one-time migration:

   INSERT INTO public.user_roles (user_id, role)
   VALUES ('<auth-user-id>', 'admin')
   ON CONFLICT DO NOTHING;

4. If completely locked out, create a new user via Cloud → Auth → Users → Add user, then promote them with the SQL above.

Ownership inheritance

Today, ownership is defined by entities.created_by. Operators and admins can edit any entity. To restrict, tighten the RLS policy to created_by = auth.uid() OR has_role(auth.uid(),'admin').

Transferring ownership

-- Admin SQL
UPDATE public.entities SET created_by = '<new-owner-uid>' WHERE id = '<entity-id>';

Preventing unauthorized access

• Never bypass the runCommand server fn from the client.
• Never expose SUPABASE_SERVICE_ROLE_KEY in browser code.
• Audit /bvc/commands periodically for unexpected actors.

1. Create entity: /bvc/entities → enter slug (lowercase a–z 0–9 -) and display name → Run command → routes to dossier.
2. Add codex entries: on the dossier, enter key + JSON value. Each key is versioned automatically.
3. Publish: add a visibility codex entry: {"public": true}.
4. Verify: confirm new row appears with version incremented and previous row's superseded_by populated.
5. QR / registry: the entity slug is the routing key for the future public dossier URL (Phase 2).
6. Failure recovery: if create fails, the form's red text names the field; for slug collision, choose a unique slug.

Slug rules: 1–64 chars, only a–z 0–9 -. No spaces, no uppercase.

Every mutation flows through runCommand at src/server/commands.functions.ts. Validation runs first; the result and the failure (if any) are written to command_log.

entity.create

• Payload: { slug: string, display_name: string }
• Validation: slug 1–64 lowercase a–z 0–9 -, name 1–200 chars.
• Success: { ok: true, entity_id, result: { id, slug, display_name, status } }
• Failure: { ok: false, result: { error: "..." } } (e.g. duplicate slug, RLS denial)
• Logged: actor_id, entity_id (on success), payload, result, ok.

// example
runCommand({ data: { command: "entity.create",
  payload: { slug: "thedonuthouse", display_name: "The Donut House" } } })

codex.add

• Payload: { entity_id: uuid, key: string, value: any }
• Validation: key 1–128, value JSON ≤ 32KB.
• Behavior: inserts new row with version = previous + 1, updates previous row's superseded_by.
• Success: returns the inserted row.
• Failure: { ok: false, result: { error: "..." } }

runCommand({ data: { command: "codex.add",
  payload: { entity_id: "<uuid>", key: "address",
             value: { street: "123 Main", city: "Springfield" } } } })

Unknown commands

Return { ok: false, result: { error: "Unknown command: ..." } } and are still logged.

runCommand

• File: src/server/commands.functions.ts
• Type: TanStack createServerFn (POST), wrapped by requireSupabaseAuth middleware.
• Auth: bearer token from session; rejected with 401 otherwise.
• Input: { command: string, payload: object }
• Output: { ok: boolean, entity_id: uuid|null, result: object }
• Tables: entities, codex_entries, command_log.
• Errors: "Unauthorized" (no session), Zod validation errors, RLS denial in result.error.
• Debug: check browser network tab for the POST body and response; cross-reference /bvc/commands for the logged row.

dispatch

src/server/commands.server.ts — pure dispatcher; add a new command by registering a handler in the switch and a Zod schema in commands.functions.ts.

requireSupabaseAuth middleware

src/integrations/supabase/auth-middleware.ts — validates JWT, attaches { supabase, userId, claims } to context.

supabaseAdmin

src/integrations/supabase/client.server.ts — service-role client used only by the command-log insert. Never imported from client code.

Configured in: Lovable Cloud → Secrets (server) and the auto-generated .env (browser). Never edit .env by hand; never expose SUPABASE_SERVICE_ROLE_KEY in browser code.

Rotating safely

1. For anon/publishable keys: Cloud → API Keys → Rotate; .env updates automatically; redeploy.
2. For service role: Cloud → API Keys → Rotate service role; update the secret; redeploy server fns.
3. For LOVABLE_API_KEY: use the dedicated rotate tool (do not delete + add).

• Auth settings: Cloud → Users → Auth Settings (gear). Toggle email confirmation, HIBP, providers.
• Tables: Cloud → Database → Tables.
• RLS policies: Cloud → Database → Tables → row "Auth Policies".
• Edge Functions: Cloud → Edge Functions (none deployed today; PlugOne uses TanStack server fns instead).
• Logs: Cloud → Logs → Postgres / Auth / Edge.
• Storage: Cloud → Storage → Buckets (none today).
• Inspect failed inserts: Logs → Postgres → filter by ERROR; cross-check command_log row with ok=false.
• Inspect auth users: Cloud → Users.
• Inspect command logs: open /bvc/commands as admin, or query SELECT * FROM command_log ORDER BY created_at DESC LIMIT 100.
• Common repairs: missing role row → see §4; RLS denial → confirm has_role matches; trigger missing → re-run migrations.

plugone.us is connected via Lovable's custom domain feature.

DNS records

A    @    185.158.133.1
A    www  185.158.133.1
TXT  _lovable  lovable_verify=<token from Lovable>

• SSL: provisioned automatically by Lovable (Let's Encrypt). No action required.
• Redirects: set Primary domain in Project Settings → Domains; the other redirects to it.
• Subdomains: type the full subdomain in the connect dialog; add its own A or CNAME.
• Cloudflare proxy: if proxied, enable "Domain uses Cloudflare" in Advanced (uses CNAME verification).
• Caching: keep default; do not cache HTML aggressively or auth flows break.
• Do not change: A records pointing to 185.158.133.1, the _lovable TXT record, the Primary designation.

• Frontend changes: click Publish → Update in Lovable to push to plugone.us. Preview URL updates automatically on every save.
• Backend changes (server fns, migrations, edge fns): deploy automatically — no manual step.
• Test before deploy: use the Preview URL (id-preview--*.lovable.app) before clicking Update.
• Rollback: open the Lovable history panel, find a known-good version, click Restore. Note: restoring before Cloud was added does not remove Cloud.
• Failed deployment recovery: read the build error in the Lovable chat; fix the named file; rebuild auto-runs.
• Cloning: use Lovable "Remix" to clone the project for a staging copy. Each remix gets its own Cloud project.

• Database: Cloud → Database → Backups (managed daily backups). Manual: pg_dump $SUPABASE_DB_URL > backup.sql.
• Auth users: Cloud → Users exports as CSV. Note: password hashes do not export; users must reset on restore unless a full PG dump is restored.
• Dossier / codex export:

  COPY (SELECT e.slug, c.key, c.value, c.version, c.created_at
  FROM entities e JOIN codex_entries c ON c.entity_id = e.id)
  TO STDOUT WITH CSV HEADER;

• Storage: Cloud → Storage → bucket → Download (none today).
• Command log: COPY command_log TO STDOUT WITH CSV HEADER;
• Full restore: create a new Cloud project, run the SQL dump, re-create auth users (or restore via PG dump including auth.*), redeploy frontend, point domain.

1. Open /auth → Sign up with owner email and password (≥6 chars). First user becomes admin.
2. You land on /bvc/entities. Enter slug thedonuthouse, name The Donut House. Click Run command.
3. The dossier opens at /bvc/entities/<new-id>.
4. Add codex entry: key address, value {"street":"123 Main","city":"Springfield"}.
5. Add codex entry: key hours, value {"mon":"6-2","tue":"6-2"}.
6. Publish: key visibility, value {"public": true}.
7. Open /bvc/commands (admin) — confirm three logged commands all ok = true.

Intake

• Collect business name, slug, address, hours, contact.
• Decide visibility (public / private / draft).

Verification

• Confirm slug uniqueness on /bvc/entities.
• Confirm dossier shows latest version of every key.
• Confirm command_log entry exists for every change.

Publishing

• Add visibility codex entry.
• Test public surface (Phase 2 QR/dossier link).
• Print or PDF this manual after every major change for audit.