Atlas Plan

Phase 1: Worker Foundations

Purpose: Establish Worker-native service topology, runtime config parity, and auth/session primitives.

T-001 - Create @services/api scaffold

Scaffold a new Cloudflare Worker API service for dashboard data and auth endpoints, including scripts and baseline route wiring.

Status: completed
Priority: P0
Dependencies: none

Acceptance

@services/api workspace package exists with build/dev/deploy scripts.
Worker runtime entrypoint and base router are in place.
Package is registered in monorepo tooling and lint/typecheck paths.

Files

@services/api/package.json
@services/api/wrangler.jsonc
@services/api/src/**
pnpm-workspace.yaml

T-002 - Register api networking and domains

Add local/dev/prod API ports/domains to network registry and align with Worker routes.

Status: completed
Priority: P0
Dependencies: T-001

Acceptance

NETWORK.yml contains api service (15004, dev/prod domains).
@services/api/wrangler.jsonc dev/prod routes match network registry.

Files

NETWORK.yml
@services/api/wrangler.jsonc

T-003 - Align dashboard Worker deployment config

Bring dashboard deployment config to the same Cloudflare Worker pattern used in other services (wrangler config, scripts, env typing).

Status: completed
Priority: P0
Dependencies: T-001

Acceptance

@services/dashboard/wrangler.jsonc exists with dev/prod routes.
Dashboard package has explicit deploy scripts for dev and prod.
Dashboard can build and run with Worker-compatible config.

Files

@services/dashboard/wrangler.jsonc
@services/dashboard/package.json
@services/dashboard/vite.config.ts

T-004 - Implement shared simple-auth session utilities

Create reusable Worker-side session helpers for login, logout, cookie checks, and credential verification with secret-backed values.

Status: completed
Priority: P0
Dependencies: T-001

Acceptance

Auth helpers support session create/read/clear with secure cookie options.
Credential verification avoids storing plaintext credentials in repository files.
Utility is consumable by both dashboard and slides-serving Worker paths.

Files

@services/api/src/lib/auth.ts
@services/dashboard/src/lib/auth.ts
@services/slides/src/lib/auth.ts

Phase 2: Dashboard + API Refactor

Purpose: Move runtime data logic into API and enforce authentication boundaries for dashboard access.

T-005 - Add API login/logout/session endpoints

Implement API endpoints for login/logout/session status using bootstrap credentials (admin) and secret-backed password hash.

Status: completed
Priority: P0
Dependencies: T-004

Acceptance

Login endpoint validates username/password and sets session cookie.
Logout endpoint clears session cookie.
Session endpoint returns authenticated/unauthenticated status for UI checks.

Files

@services/api/src/routes/auth.ts
@services/api/src/worker.ts

T-006 - Implement API read endpoints for dashboard views

Expose API routes for overview/revenue/orders/programs/schools/marketing plus student/org detail drill-down reads.

Status: completed
Priority: P0
Dependencies: T-001, T-005

Acceptance

API routes return data required by all current dashboard pages.
Routes use Turso/Drizzle-backed queries and scoped input validation.
Unauthenticated requests are denied consistently.

Files

@services/api/src/routes/dashboard.ts
@services/api/src/lib/db.ts

T-007 - Switch dashboard loaders to API calls

Replace dashboard page-level direct DB query logic with API calls via server functions.

Status: completed
Priority: P0
Dependencies: T-006

Acceptance

Dashboard routes call API endpoints for all page data.
Existing page UX/data shape remains intact.
Direct runtime DuckDB reads are removed from protected user paths.

Files

@services/dashboard/src/routes/_app/index.tsx
@services/dashboard/src/routes/_app/revenue.tsx
@services/dashboard/src/routes/_app/orders.tsx
@services/dashboard/src/routes/_app/programs.tsx
@services/dashboard/src/routes/_app/schools.tsx
@services/dashboard/src/routes/_app/marketing.tsx
@services/dashboard/src/routes/_app/students.$id.tsx
@services/dashboard/src/routes/_app/organizations.$id.tsx

Create login/logout flows and guard protected app routes before rendering.

Status: completed
Priority: P0
Dependencies: T-005

Acceptance

/login route exists with username/password form.
Protected dashboard routes redirect unauthenticated users to /login.
Logout path is available from app layout.

Files

@services/dashboard/src/routes/login.tsx
@services/dashboard/src/routes/_app.tsx
@services/dashboard/src/routes/__root.tsx

T-009 - Harden dashboard/API auth behavior

Ensure direct server-function/API access without session is blocked and cookie flags are secure for dev/prod.

Status: completed
Priority: P1
Dependencies: T-008

Acceptance

Unauthorized direct server calls return auth failures.
Cookie settings include HttpOnly, Secure (prod), SameSite, and bounded TTL.
Auth behavior is documented for local and deployed environments.

Files

@services/dashboard/src/lib/auth.ts
@services/api/src/lib/auth.ts
@services/dashboard/README.md

Phase 3: Slides R2 Delivery + Auth

Purpose: Serve report artifacts from R2 with authenticated access and stable subpath contracts.

T-010 - Create slides serving Worker

Add Worker entrypoint for slides/report delivery, including login/logout/session checks and authenticated file serving.

Status: completed
Priority: P0
Dependencies: T-004

Acceptance

Slides Worker exposes /login, /logout, and protected report routes.
Unauthenticated access redirects/challenges consistently.
Authenticated requests can stream R2 objects.

Files

@services/slides/src/worker.ts
@services/slides/src/routes/auth.ts

T-011 - Configure slides Worker + R2 bindings

Create wrangler config and scripts for slides Worker with env-specific R2 bindings and routes.

Status: completed
Priority: P0
Dependencies: T-010

Acceptance

@services/slides/wrangler.jsonc has dev/prod routes and R2 bindings.
Buckets map to pra-atlas-dev (dev) and pra-atlas-prod (prod).
Deploy scripts exist in @services/slides/package.json.

Files

@services/slides/wrangler.jsonc
@services/slides/package.json

T-012 - Add artifact publish/upload command

Create a command path to upload built web/PDF/PPTX outputs into R2 key prefixes.

Status: completed
Priority: P1
Dependencies: T-011

Acceptance

Upload command supports entity/period targeting.
Output keys follow reports/{entity}/{period}/... contract.
Build/export + upload flow is non-interactive for CI.

Files

@services/slides/cli.ts
@services/slides/scripts/upload.ts

T-013 - Enforce safe subpath routing rules

Handle /reports/{entity}/{period}/, /report.pdf, /report.pptx paths with safe normalization and clear 404 behavior.

Status: completed
Priority: P1
Dependencies: T-010

Acceptance

Directory index path resolves to web deck entry object.
Path traversal and malformed path tokens are rejected.
Missing artifacts return consistent 404 responses.

Files

@services/slides/src/worker.ts
@services/slides/README.md

Phase 4: GitHub Actions

Purpose: Add CI and manual deployment workflows for plan, dashboard/api, and slides.

T-014 - Create monorepo CI workflow

Add repository CI workflow for lint, typecheck, and tests on pull requests and main pushes.

Status: completed
Priority: P0
Dependencies: none

Acceptance

CI workflow runs pnpm install, lint, typecheck, and tests.
Workflow triggers are set for PR and main branch updates.

Files

.github/workflows/ci.yml

T-015 - Create plan deploy workflow

Add dedicated manual deploy workflow for @services/plan (dev/prod inputs).

Status: completed
Priority: P1
Dependencies: T-014

Acceptance

workflow_dispatch includes environment input.
Workflow runs plan build + wrangler deploy with environment wiring.

Files

.github/workflows/deploy-plan.yml

T-016 - Create dashboard/api deploy workflow

Add a manual deploy workflow that builds and deploys dashboard and api services for selected environment.

Status: completed
Priority: P0
Dependencies: T-003, T-014

Acceptance

Workflow deploys both @services/dashboard and @services/api.
Environment-scoped secrets/vars are used without hardcoding.
Deployment order ensures API availability before dashboard traffic.

Files

.github/workflows/deploy-dashboard-api.yml

T-017 - Create slides deploy workflow

Add manual workflow to build/export slides, upload to R2, and deploy slides-serving Worker.

Status: completed
Priority: P0
Dependencies: T-012, T-014

Acceptance

Inputs include entity, period, and environment.
Workflow performs build/export/upload and deploys slides Worker.
R2 upload targets correct env bucket.

Files

.github/workflows/deploy-slides.yml

T-018 - Document GitHub environments and secrets

Document required dev/prod GitHub environments, secret names, and approval policy expectations.

Status: completed
Priority: P1
Dependencies: T-015, T-016, T-017

Acceptance

Required secrets list is documented for all workflows.
dev and prod environment behavior is described clearly.
Production approval policy guidance is included.

Files

README.md
@plan/architecture.md

Phase 5: Docs and Rollout Validation

Purpose: Keep architecture documentation synchronized and verify implementation quality.

T-019 - Update architecture docs for api and auth flow

Document new service topology (dashboard -> api -> turso), slides R2 delivery, and auth boundaries.

Status: completed
Priority: P0
Dependencies: T-007, T-013

Acceptance

@plan/architecture.md reflects API service and new runtime flow.
Slides delivery/auth flow is documented.
Data-layer notes reflect Turso runtime mart consumption path.

Files

@plan/architecture.md
@plan/analytics.md

T-020 - Update project state and rollout notes

Record plan progress and rollout decisions in project state docs after major milestones.

Status: completed
Priority: P1
Dependencies: T-019

Acceptance

@plan/state.md reflects current phase and major decisions.
Open risks and next milestones are listed.

Files

@plan/state.md

T-021 - Run end-to-end validation checklist

Execute lint/type/test/build checks and perform basic deployed-path smoke tests for auth and subpath report access.

On this page