docs/SAAS_INTEGRATION_READINESS.md

Aureon SaaS Integration Readiness

Current tracked snapshot: 2026-07-13.

This document turns the repo-wide sitemap into a SaaS integration checklist. It identifies source surfaces, end-user access paths, environment variables, auth boundaries, generated artifacts, and production gates that must stay visible for safe integration.

End-user auth & per-tenant keys: the identity model (open / admin / tenant), the per-tenant encrypted keystore, and the no-cross-tenant-leak invariant are documented in architecture/MULTI_TENANT_AUTH.md. Turn tenancy on with AUREON_SUPABASE_JWT_SECRET; unset ⇒ single-operator, unchanged.

Primary map: REPO_SITEMAP.md. Machine-readable map: repo_sitemap.json. Machine-readable SaaS integration manifest: saas_integration_manifest.json, mirrored to ../frontend/public/aureon_saas_integration_manifest.json. Machine-readable SaaS integration handoff: saas_integration_handoff.json, mirrored to ../frontend/public/aureon_saas_integration_handoff.json. Supabase hardening review: SUPABASE_HARDENING_REVIEW.md, with generated manifest supabase_hardening_manifest.json mirrored to ../frontend/public/aureon_supabase_hardening_manifest.json. Autonomous frontend manifests are mounted as public, audit-backed JSON for the operator console: SaaS inventory, frontend unification plan, frontend evolution queue, organism runtime status, and autonomous capability switchboard. End-user task map: END_USER_ACCESS_MAP.md. Frontend console route: #repo-map, implemented by ../frontend/src/components/RepoNavigationPanel.tsx. File-level navigation index: repo_navigation_index.json, mirrored to ../frontend/public/aureon_repo_navigation_index.json. Directory organization tree: repo_organization_tree.json, mirrored to ../frontend/public/aureon_repo_organization_tree.json. Navigation readiness audit: repo_navigation_readiness.json, mirrored to ../frontend/public/aureon_repo_navigation_readiness.json. Navigation completion audit: repo_navigation_completion_audit.json, mirrored to ../frontend/public/aureon_repo_navigation_completion_audit.json. Capability access matrix: capability_access_matrix.json, mirrored to ../frontend/public/aureon_capability_access_matrix.json. System integration map: SYSTEM_INTEGRATION_MAP.md, with generated manifest system_integration_map.json mirrored to ../frontend/public/aureon_system_integration_map.json. Capability registry: CAPABILITY_REGISTRY.md, with generated registry capability_registry.json mirrored to ../frontend/public/aureon_capability_registry.json. Manifest generation and validation, from repo root: python scripts/validation/generate_repo_navigation_index.py, then python scripts/validation/generate_saas_integration_manifest.py, then python scripts/validation/generate_supabase_hardening_manifest.py, then python scripts/validation/generate_system_integration_map.py, then python scripts/validation/generate_capability_registry.py, then python scripts/validation/generate_repo_navigation_readiness.py, then python scripts/validation/generate_saas_integration_handoff.py, then python scripts/validation/generate_repo_navigation_completion_audit.py, then python scripts/validation/validate_repo_navigation_contract.py.

Canonical Integration Shape

Use this shape when turning the repo into a product or SaaS workflow:

End user
  -> frontend/ React/Vite console
  -> public/static artifacts and generated frontend mirrors
  -> Supabase functions, migrations, and auth-gated data plane
  -> local or hosted Aureon runtime connector
  -> operator-controlled live-action routes
  -> evidence ledgers, audit files, and generated state

The safest current product posture is local-first SaaS integration: the browser and Supabase surfaces can be hosted, while trading, warehouse, filing, payment, desktop, and sensitive mutation routes remain operator-controlled and separately gated.

End-User Access Matrix

User need	Entry point	Related systems	Access mode	Gate before production
Understand the product	../README.md, REPO_SITEMAP.md	docs/, docs/investor/	Public docs	Keep claims evidence-backed.
Browse all capabilities	../CAPABILITIES.md, REPO_SITEMAP.md	aureon/, frontend/, data/, Kings_Accounting_Suite/	Public docs	Keep capability status current.
Run locally	../RUNNING.md	Root launchers, aureon/, frontend/	Local operator	Validate .env and dry-run/live flags.
Use the web console	frontend/	frontend/src/, frontend/public/, public/	Browser app	Confirm build env and runtime data source.
Navigate capabilities in a SaaS shell	END_USER_ACCESS_MAP.md, repo_navigation_index.json, repo_organization_tree.json, repo_navigation_completion_audit.json, capability_access_matrix.json, capability_registry.json, system_integration_map.json, saas_integration_manifest.json, saas_integration_handoff.json, supabase_hardening_manifest.json, frontend #repo-map	docs/, docs/audits/, frontend/public/, frontend/src/components/RepoNavigationPanel.tsx	Static JSON manifests, file-level index, directory tree, completion audit, capability access matrix, capability registry, system integration map, SaaS integration contract, integration handoff, Supabase hardening contract, autonomous frontend manifests, and console tab	Keep public manifests secret-free.
Read runtime state	http://127.0.0.1:8791/api/terminal-state	aureon/exchanges/, status server	Local HTTP	Do not expose publicly without auth and redaction.
Read thought/action state	http://127.0.0.1:13002/api/thoughts	Mind hub, self-questioning loop	Local HTTP	Do not expose publicly without auth and redaction.
Trigger coding workflow	/api/coding/prompt and /api/coding/status	aureon/autonomous/, aureon/code_architect/, skills/	Local operator/API	Keep code proposals review-gated.
Review grant/funder evidence	data/research/grants/, docs/investor/	Grant ledgers, copied evidence, pipeline JSON	Public or controlled disclosure	Redact private evidence before sharing.
Use accounting/filing support	Kings_Accounting_Suite/	Accounting tools and support packs	Local operator	Filing remains manual unless separately authorized.
Integrate hosted backend	supabase/, api/, server/, functions/, netlify/	Supabase functions, Node bridges, serverless routes	Hosted/API	Apply auth matrix below before production.
Deploy product surface	deploy/, production/, app.yaml, Docker files	DigitalOcean, Docker, Netlify, Cloudflare, Supabase	Hosted deployment	Choose one target and maintain an env inventory.

Environment Variable Inventory

This inventory is based on .env.example, deploy/env.example, and app.yaml. It lists variable names only, not secret values.

Group	Variables	Source
Supabase frontend	VITE_SUPABASE_URL, VITE_SUPABASE_PUBLISHABLE_KEY	app.yaml
Supabase runtime	SUPABASE_URL, SUPABASE_ANON_KEY	app.yaml
Exchange credentials	KRAKEN_API_KEY, KRAKEN_API_SECRET, BINANCE_API_KEY, BINANCE_API_SECRET, ALPACA_API_KEY, ALPACA_SECRET_KEY, CAPITAL_API_KEY, CAPITAL_IDENTIFIER, CAPITAL_PASSWORD	.env.example, deploy/env.example, app.yaml
Exchange mode flags	KRAKEN_DRY_RUN, BINANCE_DRY_RUN, ALPACA_DRY_RUN, ALPACA_PAPER, CAPITAL_DEMO, CAPITAL_DEMO_MODE, BINANCE_UK_MODE, BINANCE_USE_TESTNET, BINANCE_TESTNET, USE_TESTNET	.env.example, deploy/env.example, app.yaml
Runtime/platform	PORT, MODE, PYTHONIOENCODING, PYTHONUNBUFFERED, AUREON_STATE_DIR, AUREON_REDIS_URL, KRAKEN_NONCE_PATH, KRAKEN_PRIVATE_LOCK_PATH	deploy/env.example, app.yaml
Safety and product switches	LIVE, REAL_DATA_ONLY, AUREON_DRY_RUN, DRY_RUN, PAPER_TRADING, PAPER_MODE, PAPER, SIMULATION_MODE, DEMO_MODE, STATUS_MOCK, IG_DEMO, AUREON_COMMAND_CENTER_DEMO, SIMULATED_ATTACKS, SENTIENCE_FORCE_PERFECT, AUREON_ENABLE_AUTONOMOUS_CONTROL, AUREON_REQUIRE_ALL_EXCHANGES, AUREON_SKIP_KRAKEN_SEED	deploy/env.example, app.yaml
Feature enablement	ENABLE_ALPACA, ENABLE_KRAKEN, ENABLE_BINANCE, ENABLE_CAPITAL, STARTING_CAPITAL	deploy/env.example
Optional data providers	COINAPI_KEY	.env.example

Production rule: keep credentials in the target secret store. Do not commit filled .env files, customer identifiers, exchange passwords, or private evidence exports.

Deployment Surfaces

Surface	Files	Current role	Readiness note
Local Windows operator	scripts/launchers/AUREON_PRODUCTION_LIVE.cmd, scripts/launchers/AUREON_WAKE_UP_FULL_AUTONOMOUS.ps1, RUNNING.md	Current primary local run path.	Best current source of truth for operator startup.
Frontend app	frontend/package.json, frontend/src/, frontend/public/	React/Vite product surface.	Build with npm run build; confirm env values before hosted use.
Supabase backend	supabase/config.toml, supabase/functions/, supabase/migrations/	Hosted functions, auth settings, schema migrations.	Auth matrix and hardening review below must be resolved before production.
DigitalOcean App Platform	app.yaml, deploy/	App spec and startup scripts.	Already names main and env keys; secrets must be configured in platform.
Docker/production package	Dockerfile, docker-compose.yml, production/	Container and installer assets.	Current production docs include older language; use sitemap/readiness docs as current public framing.
Node/server bridge	server/	Optional WebSocket/server bridge.	Treat as component surface, not canonical product API until reviewed.
Serverless routes	api/, functions/, netlify/, deploy/cloudflare/	RSS/proxy/worker style routes.	Confirm auth, CORS, and data redaction per route.

Supabase Auth Boundary

Current supabase/config.toml declares 87 functions:

Auth mode	Count	Production interpretation
verify_jwt = true	73	Auth-gated; still needs role-level and payload validation review.
verify_jwt = false	14	Public at Supabase edge; must be read-only, anonymous-safe, or separately protected in function code before production.

The generated hardening manifest classifies those functions by public exposure, mutation/ingest/sensitive-state signals, and required controls. The current manifest identifies zero high-risk public routes blocking production: supabase_hardening_manifest.json.

Public functions currently configured with verify_jwt = false:

fetch-kraken-market-data, sync-exchange-assets, aureon-chat, ingest-telescope-state, fetch-binance-market-data, fetch-schumann-data, fetch-all-tickers, verify-exchange-connectivity, interpret-frequency, ingest-10-9-1-packet, backend-health-check, ingest-auris-state, ingest-kelly-computation, and ai-commentary.

Public endpoint production gates:

• Market-data fetchers and health checks can remain public only if they expose no user credentials, account balances, private positions, or private evidence.
• Public ingestion routes must validate source, schema, size, rate limits, and replay behavior before public hosting.
• force-validated-trade, confirm-trade, poll-trade-confirmations, test-exchange-connection, ingest-trades, ingest-terminal-state, and ingest-brain-state are now JWT gated and remain subject to explicit role/payload review before production because their names or purpose imply mutation, user-sensitive validation, or operational state writes.
• Auth-gated trade, balance, gas-tank, emergency-stop, credential, monitor, and user-market routes must remain JWT-gated and need role/payload checks inside each function.
• Regenerate the hardening manifest after any Supabase function auth change so the docs and frontend public mirror keep the same blocker count.

Generated Artifact Policy

Artifact class	Examples	Policy
Source docs	README.md, docs/REPO_SITEMAP.md, docs/SAAS_INTEGRATION_READINESS.md	Tracked and reviewed.
Public static/generated assets	frontend/public/	Tracked when intentionally published; runtime mirrors may be generated.
Public navigation manifests	frontend/public/aureon_repo_sitemap.json, frontend/public/aureon_end_user_access_map.json, frontend/public/aureon_capability_access_matrix.json, frontend/public/aureon_capability_registry.json, frontend/public/aureon_repo_navigation_index.json, frontend/public/aureon_repo_organization_tree.json, frontend/public/aureon_repo_navigation_readiness.json, frontend/public/aureon_repo_navigation_completion_audit.json, frontend/public/aureon_system_integration_map.json, frontend/public/aureon_saas_integration_manifest.json, frontend/public/aureon_saas_integration_handoff.json, frontend/public/aureon_supabase_hardening_manifest.json, frontend/public/aureon_saas_system_inventory.json, frontend/public/aureon_frontend_unification_plan.json, frontend/public/aureon_frontend_evolution_queue.json, frontend/public/aureon_organism_runtime_status.json, frontend/public/aureon_autonomous_capability_switchboard.json	Tracked, secret-free access contracts, capability access matrix, capability registry, file-level index, directory tree, navigation readiness audit, completion audit, system integration map covering all current implementation capabilities, SaaS integration manifest, SaaS integration handoff, Supabase hardening manifest, SaaS inventory, frontend unification plan, evolution queue, organism status, and capability switchboard for UI/SaaS shells.
Runtime state	state/aureon_wake_up_manifest.json, state/aureon_data_ocean_status.json, local SQLite registries	Generated locally unless explicitly committed. Do not treat absence from git as missing source.
Audit outputs	docs/audits/* named in run docs	Generated by runtime/audit jobs; commit only curated public-safe outputs.
Private evidence	Screenshots, customer data, credentials, transaction records, local live ledgers	Keep private unless redacted and intentionally published.
Archives/imports	archive/, docs/archive/, imports/	Preserve for provenance; do not use as current product copy.

SaaS Production Gates

Before calling a hosted deployment production-ready, complete these gates:

1. Choose one canonical target for the hosted product surface.
2. Confirm all required environment variables for that target and store secrets in the platform secret store.
3. Review every public Supabase function using python scripts/validation/generate_supabase_hardening_manifest.py; either prove it is anonymous-safe or gate it with JWT plus role checks.
4. Define CORS, rate limits, payload limits, logging, and redaction policy for hosted API routes.
5. Decide which runtime JSON artifacts are generated locally, mirrored to frontend public assets, or persisted in Supabase.
6. Keep live trading, warehouse mutation, filing, payment, desktop control, and security-testing actions operator-controlled.
7. Run python scripts/validation/generate_repo_navigation_index.py after broad file moves. Run python scripts/validation/generate_repo_organization_tree.py after hierarchy or broad file moves. Run python scripts/validation/generate_capability_access_matrix.py after capability route changes. Run python scripts/validation/generate_system_integration_map.py after system or public-artifact routing changes. Run python scripts/validation/generate_capability_registry.py after capability table or surface-reference changes. Run python scripts/validation/generate_saas_integration_manifest.py after env or deployment changes. Run python scripts/validation/generate_supabase_hardening_manifest.py after Supabase auth or function changes. Run python scripts/validation/generate_repo_navigation_readiness.py after regenerating navigation, capability, system, SaaS, or hardening manifests. Run python scripts/validation/generate_saas_integration_handoff.py after regenerating readiness, SaaS, or hardening manifests. Run python scripts/validation/generate_repo_navigation_completion_audit.py after regenerating readiness or handoff manifests. Then run python scripts/validation/validate_repo_navigation_contract.py after navigation, public manifest, file-index, capability-registry, system-integration-map, SaaS-manifest, handoff-manifest, completion-audit-manifest, hardening-manifest, or Supabase auth-setting changes.
8. Run the relevant local checks in RUNNING.md and the target deployment smoke checks before publishing an external URL.