diff --git a/docs/architecture.md b/docs/architecture.md index 27094a4..f993716 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -46,6 +46,17 @@ flowchart LR CI -. deploys .-> PRIVATE ``` +## Judge-facing architecture diagram + +The companion diagram below presents the same public and private boundaries in +plain language for both technical and non-technical reviewers. Solid arrows are +live public-path calls; dashed arrows are optional, private-only integrations. + +![StayLong architecture: from a home concern to an assessment-ready plan](assets/architecture/staylong-architecture.svg) + +The editable [draw.io source](assets/architecture/staylong-architecture.drawio) +is included for review and future updates. + The demo seed is [`fixtures/demo/seeded-household.json`](../fixtures/demo/seeded-household.json). It exercises the normal concern → intake → draft → human approval path with synthetic identifiers only; it does not represent a real household or execute an external side effect. ## Components @@ -116,6 +127,6 @@ Emergency handling is a static, deterministic route, not an LLM feature. A possi - The branded public entry point is `https://staylonghome.com`, served by a global external HTTPS Load Balancer, Google-managed TLS certificate and Serverless NEG in front of Cloud Run; direct Cloud Run domain mapping is not used. During Phase A, the existing generated `run.app` URL remains available as a rollback path. Phase B can restrict direct Cloud Run access only after branded-domain TLS, smoke tests and evidence have passed. The detailed boundary, lifecycle controls and DNS-token handling are in the -[public-edge design](architecture/public-edge-design.md). The public edge is +[public-edge design](public-edge-design.md). The public edge is still a temporary-data sandbox: it does not provide real Calendar, Gmail, SMS, provider, payment, MyGov or government-account actions. diff --git a/docs/assets/architecture/staylong-architecture.drawio b/docs/assets/architecture/staylong-architecture.drawio new file mode 100644 index 0000000..ab81763 --- /dev/null +++ b/docs/assets/architecture/staylong-architecture.drawio @@ -0,0 +1,116 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/assets/architecture/staylong-architecture.svg b/docs/assets/architecture/staylong-architecture.svg new file mode 100644 index 0000000..2e63697 --- /dev/null +++ b/docs/assets/architecture/staylong-architecture.svg @@ -0,0 +1,215 @@ + + + StayLong architecture + A judge-friendly view of StayLong's approval-safe ageing-in-place coordination architecture, from the older person's web experience through the public demo, bounded agentic coordination core, approval boundary and Google Cloud delivery controls. + + + + + + + StayLong | Approval-safe ageing-in-place coordination + From a home concern to an assessment-ready plan — with the older person in control of every external action. + + Built and operated on Google Cloud + + + + + 1 · YOUR EXPERIENCE + + + 2 · PUBLIC DEMO — SAFE BY DESIGN + + + 3 · AGENTIC COORDINATION CORE + + + 4 · YOU STAY IN CONTROL + + + + + + + invited + + + + + + + + + + + + + + + + + + + + + + + + + + + proposal + + + public demo + + + optional private OAuth + + + private draft + + + + Older personLiving independently at home + + Trusted supporterOptional, only when invited + + + StayLong web experienceAccessible, guided intake and plan + + VALUETurns an everyday concern into clear,assessment-ready information. + + + + + + Cloudflare DNS + staylonghome.com + + + + + + Global HTTPS load balancer + Google-managed TLS · Serverless NEG + + + + + + Cloud Run · public sandbox + Anonymous sessions · synthetic data + + + PUBLIC MEANS SAFE TO TRYNo real MyGov, provider, payment, Calendar,Gmail or SMS action. + + + + + + Deterministic safety route + Bounded inputs and policy checks + + G + + Gemma 4 privacy guardVertex Model Garden MaaS · fail closed + AI + + Google ADK coordinatorGemini 3.6 Flash prepares a bounded plan + + + + + Firestore case state + Plan, approvals and audit timeline + + + + + + Cloud Tasks / Pub/Sub + Approved work and follow-through + + + + A COORDINATION LAYER — NOT A DECISION MAKERDoes not determine eligibility, choose providers, prescribe changes or make payments. + + + Approval gateYou choose before anythingexternal happens + + + + + Public sandbox action + Recorded simulation only + + + + + + Private runtime · optional OAuth + Google Calendar · create only after approval + + + + + + Private contact draft + Gmail draft only · never sent automatically + + + + Built, delivered and observed on Google Cloud + Infrastructure is declared in code, deployed without long-lived cloud keys, and monitored with privacy-safe timing logs. + + + + + + + + + + + + + + GitHub Actions + Checks and deployment workflows + + + + + + Workload Identity Federation + No long-lived service-account keys + + + + + + Terraform + Cloud Run, routing and policies as code + + + + + + Cloud Logging + Privacy-safe workflow timing evidence + + + Legend━━ actual flow┄┄ optional private◆ approval + Public demo: anonymous sessions, synthetic data and sandbox actions. Private runtime: IAM access and user-approved OAuth only. + diff --git a/docs/architecture/public-edge-design.md b/docs/public-edge-design.md similarity index 100% rename from docs/architecture/public-edge-design.md rename to docs/public-edge-design.md diff --git a/docs/superpowers/plans/2026-08-28-public-edge.md b/docs/superpowers/plans/2026-08-28-public-edge.md index dd5e1de..b6b2933 100644 --- a/docs/superpowers/plans/2026-08-28-public-edge.md +++ b/docs/superpowers/plans/2026-08-28-public-edge.md @@ -8,7 +8,7 @@ **Tech Stack:** Terraform >= 1.9; hashicorp/google ~> 6; cloudflare/cloudflare ~> 5; Google Cloud Load Balancing; Cloud Run; GitHub Actions; pytest; Trivy. -**Spec:** `docs/architecture/public-edge-design.md` +**Spec:** `docs/public-edge-design.md` ## Global Constraints