Workers Deployment and Simple Auth

Overview

Deploy Atlas fully on Cloudflare Workers by introducing a dedicated @services/api runtime service, refactoring @services/dashboard to stop handling direct data logic, and adding a protected @services/slides delivery path backed by R2.

This plan also introduces a bootstrap simple-auth flow (one user for now: admin) for dashboard and slides, plus GitHub Actions workflows for CI and per-service deployment (plan, dashboard/api, slides) using manual environment promotion.

Goals

• Create and deploy a Worker-native @services/api service with Turso as the primary runtime database.
• Refactor @services/dashboard into UI/BFF behavior, with auth and data access routed through API boundaries.
• Serve slides and report artifacts from R2 using subpath URLs with authentication gates.
• Add GitHub Actions workflows for CI and deploys (including @services/plan) with dev/prod separation.
• Keep architecture and network docs aligned with implementation in the same change sets.

Non-Goals

• Migrating runtime storage to D1 in this phase.
• Building full SSO/MFA or Cloudflare Access policy rollout in this phase.
• Removing dbt/DuckDB from offline analytics generation workflows.

Phases

• Phase 1: Worker topology and runtime foundations (api, dashboard deploy parity, auth primitives)
• Phase 2: Dashboard + API refactor (auth gates and API-driven data)
• Phase 3: Slides delivery worker (R2-backed, authenticated, subpath routing)
• Phase 4: GitHub Actions (CI and service deploy workflows)
• Phase 5: Architecture/state docs and rollout validation

Success

• @services/api exists, deploys to Workers, and serves dashboard-required endpoints from Turso.
• @services/dashboard no longer depends on direct DuckDB runtime reads for user-facing routes.
• Dashboard and slides require authenticated session access; unauthenticated requests redirect to login.
• Slides/report assets are accessible by approved subpaths from R2 (/reports/{entity}/{period}/...).
• Separate GitHub Actions workflows exist for CI, plan deploy, dashboard/api deploy, and slides deploy.
• NETWORK.yml and relevant @plan/ docs are updated to reflect final architecture.

Requirements

• Cloudflare account with route control for dashboard, api, slides, and plan domains.
• Turso credentials (DATABASE_URL, TURSO_AUTH_TOKEN) for Worker runtime queries.
• R2 buckets: pra-atlas-dev and pra-atlas-prod.
• GitHub repository secrets for Cloudflare deploy tokens/account and runtime env vars.
• Local validation ability: pnpm lint, pnpm test:type, pnpm test, service build commands.

Context

Why This Approach

• User requested all runtime deployment targets to be Cloudflare Workers.
• Existing dashboard runtime uses native DuckDB bindings, which are not ideal for Worker-native production execution.
• Splitting API from dashboard improves service boundaries, allows independent auth/rate-limiting, and simplifies dashboard rendering concerns.
• R2 is the requested storage backend for slides/report artifacts and naturally supports key-prefix/subpath organization.

Key Constraints

• Runtime DB decision is fixed for this phase: Turso first, marts published to Turso only.
• API must be externally reachable by public domain and can additionally use internal service binding.
• Deployment model is manual environment dispatch (dev/prod) with separate workflow for @services/plan.
• Local port and domain allocation must follow NETWORK.yml conventions (prefix 15xxx).

Edge Cases

• Direct server-function/API calls must be blocked when no session cookie is present (not only route-level UI checks).
• Slides subpath routing must prevent path traversal and ambiguous key resolution.
• Report folders may exist without both report.pdf and report.pptx; directory/index behavior should fail clearly.
• Auth bootstrap should avoid committing plaintext credentials while still allowing initial admin login setup.

Tradeoffs

• Simple auth is intentionally lightweight and fast to ship, but weaker than Access/SSO (no MFA, manual rotation).
• Turso-first accelerates migration but postpones deeper Cloudflare-native D1 alignment.
• Introducing an API service adds operational complexity but gives cleaner separation and safer evolution.

Skills

• cloudflare - Workers, R2, service routing, environment bindings
• wrangler - Worker config/deploy patterns and env management
• hono - API service structure and middleware patterns for Workers
• turborepo - Monorepo task/workflow alignment
• react-best-practices - Dashboard route/data refactor guardrails

Boundaries

• Always: Keep credentials and session secrets in runtime secrets/variables, never committed plaintext.
• Always: Protect dashboard and slides at middleware/server layers, not only client UI.
• Always: Update NETWORK.yml and architecture docs in the same implementation stream.
• Ask first: Any destructive data migration affecting existing operational data.
• Ask first: Any change that broadens public unauthenticated access to reports or API.
• Never: Store admin123 directly in source code or tracked config files.
• Never: Introduce force-push/destructive git operations as part of this rollout.

Questions

• Runtime DB for @services/api? -> Turso first.
• Where do runtime marts live? -> Turso only for now.
• API exposure model? -> Public API domain, with optional internal binding.
• Slides artifact storage? -> R2 buckets (pra-atlas-dev, pra-atlas-prod).
• Deploy trigger model? -> Manual environment deploy workflows.
• Plan service deploy workflow separate? -> Yes, separate workflow file.
• When should simple auth be replaced with Cloudflare Access/SSO?