Atlas Plan

Phase 1: Package Scaffold

Purpose: Create all configuration files for the dashboard service

T-001 - Scaffold @services/dashboard config files

Create package.json, tsconfig.json, eslint.config.mjs, vite.config.ts, app.config.ts, components.json.

Status: pending
Priority: P0
Dependencies: none

Acceptance

package.json: name @services/dashboard, scripts (dev/build/lint/test:type), deps via catalog references including TanStack Start, TanStack Router, TanStack Query, shadcn/ui, tailwindcss; workspace deps: @packages/db, @packages/format
tsconfig.json extending @repo/typescript/tanstack, paths for @/* and ~/*
eslint.config.mjs using base() from @repo/lint/base
vite.config.ts with port 15002, allowed host dashboard.atlas.test, all plugins (tanstack-start, react, tailwind)
app.config.ts with preset: 'cloudflare-module'
components.json for shadcn/ui configuration
.gitignore covering node_modules, dist, .tanstack, .wrangler

Files

@services/dashboard/package.json
@services/dashboard/tsconfig.json
@services/dashboard/eslint.config.mjs
@services/dashboard/vite.config.ts
@services/dashboard/app.config.ts
@services/dashboard/components.json
@services/dashboard/.gitignore

T-002 - Update NETWORK.yml with dashboard entry

Status: pending
Priority: P0
Dependencies: none

Acceptance

NETWORK.yml has services.dashboard entry
local.ports.dev: 15002
Local domain: dashboard.atlas.test
Dev domain: dev.dashboard.atlas.prata.ma
Prod domain: dashboard.atlas.prata.ma

Phase 2: Root Layout + Data Helpers

Purpose: Create the app shell, styles, route tree seed, and server-side data client helpers

T-003 - src/styles.css and src/router.tsx

Create the CSS entry point (Tailwind) and TanStack Router factory.

Status: pending
Priority: P0
Dependencies: T-001

Acceptance

src/styles.css imports tailwindcss
src/router.tsx exports getRouter() using routeTree, scrollRestoration: true
Router type registered via declare module '@tanstack/react-router'

Files

@services/dashboard/src/styles.css
@services/dashboard/src/router.tsx

T-004 - Seed src/routeTree.gen.ts

Manually seed the route tree for initial type-check. Defines all routes: /, /_app, /_app/revenue, /_app/orders, /_app/programs, /_app/schools, /_app/marketing, /_app/students/$id, /_app/organizations/$id.

Status: pending
Priority: P0
Dependencies: T-003

Acceptance

src/routeTree.gen.ts has /* eslint-disable */ and // @ts-nocheck headers
Defines all 9 routes with correct file paths
Exports routeTree composed from all route imports

Files

@services/dashboard/src/routeTree.gen.ts

T-005 - src/routes/__root.tsx and src/routes/_app.tsx

Create the HTML document shell and the shared app layout with sidebar navigation.

Status: pending
Priority: P0
Dependencies: T-004

Acceptance

__root.tsx: HTML shell with <title>Atlas Dashboard</title>, CSS import, suppressHydrationWarning
_app.tsx: sidebar layout with nav links to all 8 routes; <Outlet /> for content
Nav labels: Overview, Revenue, Key Metrics, Programs, Schools, Marketing, (separator) Students, Organizations

Files

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

T-006 - lib/duck.ts — DuckDB server helper

Server-side DuckDB client helper for aggregated mart queries.

Status: pending
Priority: P0
Dependencies: T-001

Acceptance

createDuckClient() opens atlas.db (path from env or default)
query<T>(sql) returns typed rows
Exported from src/lib/duck.ts
use server compatible (no client-side imports)

Files

@services/dashboard/src/lib/duck.ts

T-007 - lib/db.ts — Drizzle/LibSQL server helper

Server-side helper wrapping @packages/db for individual record queries.

Status: pending
Priority: P0
Dependencies: T-001

Acceptance

Re-exports db from @packages/db
Exported from src/lib/db.ts

Files

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

Phase 3: Aggregated Views (DuckDB Routes)

Purpose: Implement all DuckDB-backed routes

T-008 - src/routes/_app/index.tsx — Overview

Overview route showing all-unit totals for the selected period.

Status: pending
Priority: P0
Dependencies: T-005, T-006

Acceptance

Server function queries mart_revenue grouped by unit for the selected period
Displays unit cards: unit name, revenue actuals, transaction count
Period selector (defaults to latest period in mart)

Files

@services/dashboard/src/routes/_app/index.tsx

T-009 - src/routes/_app/revenue.tsx — Revenue Comparison

Revenue comparison view backed by mart_revenue.

Status: pending
Priority: P0
Dependencies: T-006

Acceptance

Server function queries mart_revenue + stg_targets for selected unit + period
Displays: revenue actuals, target, gap, achievement %, last period, last year, best year
Unit selector and period selector
Bar chart component (shadcn/recharts or similar)

Files

@services/dashboard/src/routes/_app/revenue.tsx

T-010 - src/routes/_app/orders.tsx — Key Comparison

Key comparison view showing revenue + student type breakdown vs target.

Status: pending
Priority: P0
Dependencies: T-006

Acceptance

Server function queries mart_program_progress aggregated by customer_type for unit + period
Table: Total Revenue, Siswa Baru, Siswa Lanjut, Siswa Alumni vs target and last year
Status badge per row (Completed/On Track/Needs Attention)

Files

@services/dashboard/src/routes/_app/orders.tsx

T-011 - src/routes/_app/programs.tsx — Program Progress

Per-program breakdown for a unit + period.

Status: pending
Priority: P0
Dependencies: T-006

Acceptance

Server function queries mart_program_progress by product_name for unit + period
Table: program name, last year count, target, actuals, status
Unit and period selectors

Files

@services/dashboard/src/routes/_app/programs.tsx

T-012 - src/routes/_app/schools.tsx — School Progress

Organization × year matrix view.

Status: pending
Priority: P0
Dependencies: T-006

Acceptance

Server function queries mart_school_progress for a unit
Matrix table: organizations as rows, years as columns
Groups organizations by education level
Unit selector

Files

@services/dashboard/src/routes/_app/schools.tsx

T-013 - src/routes/_app/marketing.tsx — Channel Marketing

Channel marketing breakdown for a unit + period.

Status: pending
Priority: P0
Dependencies: T-006

Acceptance

Server function queries mart_channel_marketing for unit + period
Table: channel name, closings, students, contribution %, status
Unit and period selectors

Files

@services/dashboard/src/routes/_app/marketing.tsx

Phase 4: Individual Record Views (LibSQL Routes)

Purpose: Implement drill-down views backed by LibSQL Drizzle queries

T-014 - src/routes/_app/students.$id.tsx — Student Profile

Individual student profile backed by LibSQL db_person + commerce_order.

Status: pending
Priority: P1
Dependencies: T-007

Acceptance

Server function queries db_person by id with organization join
Queries all commerce_order records for this person as participant
Displays: name, contact info, organization, order history (unit, product, period, amount)
404 state if person not found