Atlas Plan

Phase 1: Foundation

Purpose: Add catalog entries, port policy, and content navigation config to the repo root

T-001 - Add catalog entries to root package.json

Add the react, docs, style, type, infra named catalogs and extend the build catalog with Vite/Cloudflare packages. Add next-themes to the default catalog.

Status: completed
Priority: P0
Dependencies: none

Acceptance

catalogs.react added: @tanstack/react-router, @tanstack/react-start, react, react-dom
catalogs.docs added: fumadocs-core, fumadocs-ui, fumadocs-mdx, fumadocs-core, beautiful-mermaid, mermaid, @types/mdx
catalogs.style added: tailwindcss, @tailwindcss/vite
catalogs.type added: @types/react, @types/react-dom
catalogs.infra added: wrangler
catalogs.build extended: @cloudflare/vite-plugin, @vitejs/plugin-react, vite, vite-tsconfig-paths
catalog.next-themes added to default catalog

Files

package.json

T-002 - Create NETWORK.yml

Create NETWORK.yml at repo root establishing the 15xxx port policy for ions, with the plan service registered at port 15001.

Status: completed
Priority: P0
Dependencies: none

Acceptance

NETWORK.yml exists at repo root
prefix: 15 set
services.plan entry with local.ports.dev: 15001
Local domain: plan.atlas.test
Dev domain: dev.plan.atlas.prata.ma
Prod domain: plan.atlas.prata.ma

Files

NETWORK.yml

T-003 - Create @plan/meta.json

Create meta.json in @plan/ to control Fumadocs sidebar navigation ordering.

Status: completed
Priority: P1
Dependencies: none

Acceptance

@plan/meta.json exists
Pages ordered: architecture → model → analytics → glossary → registry → domains → discussions → plans

Files

@plan/meta.json

Phase 2: Service Config

Purpose: Create all configuration files for @services/plan

T-004 - Create @services/plan config files

Create package.json, tsconfig.json, eslint.config.mjs, source.config.ts, vite.config.ts, app.config.ts, wrangler.jsonc, and .gitignore for the service.

Status: completed
Priority: P0
Dependencies: T-001

Acceptance

package.json with name @services/plan, scripts (dev/build/deploy/lint/test:type), all deps via catalog references
tsconfig.json extending @repo/typescript/tanstack, paths for @/* and fumadocs-mdx:collections/*
eslint.config.mjs using base() from @repo/lint/base
source.config.ts pointing to ../../@plan with correct glob patterns
vite.config.ts with port 15001, allowed host plan.atlas.test, all plugins
app.config.ts with preset: 'cloudflare-module'
wrangler.jsonc with worker name pra-atlas-plan, dev/prod env routing
.gitignore covering node_modules, dist, .source, .tanstack, .wrangler

Files

@services/plan/package.json
@services/plan/tsconfig.json
@services/plan/eslint.config.mjs
@services/plan/source.config.ts
@services/plan/vite.config.ts
@services/plan/app.config.ts
@services/plan/wrangler.jsonc
@services/plan/.gitignore

Phase 3: Source Files

Purpose: Implement all src/ files ported from the reference implementation with ions-specific branding

T-005 - Create src/styles.css and src/router.tsx

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

Status: completed
Priority: P0
Dependencies: T-004

Acceptance

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

Files

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

T-006 - Create src/routeTree.gen.ts

Seed the auto-generated route tree file. This is normally generated by TanStack Router on vite dev, but must exist for tsc --noEmit to pass before first dev run.

Status: completed
Priority: P0
Dependencies: T-005

Acceptance

src/routeTree.gen.ts exists with /* eslint-disable */ and // @ts-nocheck headers
Defines all 4 routes: /, /api/search, /docs/$, /docs/
Exports routeTree composed from all route imports
Registers @tanstack/react-start SSR types

Notes

Copy verbatim from reference: /Users/bianpratama/Code/pra/pilot/@services/plan/src/routeTree.gen.ts
No changes needed — route structure is identical

Files

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

T-007 - Create src/routes/__root.tsx

Create the app shell route with HTML document structure, Fumadocs RootProvider, and CSS import.

Status: completed
Priority: P0
Dependencies: T-006

Acceptance

<title> set to Atlas Plan (not Pilot Plan)
RootProvider from fumadocs-ui/provider/tanstack wraps <Outlet />
CSS imported via @/styles.css?url
suppressHydrationWarning on <html> for dark mode SSR compatibility

Files

@services/plan/src/routes/__root.tsx

T-008 - Create src/routes/index.tsx and src/routes/docs/index.tsx

Create the root redirect (/ → /docs) and the docs index redirect (/docs → /docs/architecture).

Status: completed
Priority: P0
Dependencies: T-006

Acceptance

src/routes/index.tsx redirects / → /docs
src/routes/docs/index.tsx redirects /docs → /docs/$ with _splat: 'architecture' (lowercase)

Notes

The reference redirects to 'ARCHITECTURE' (uppercase). For ions, use 'architecture' to match the lowercase filename in @plan/

Files

@services/plan/src/routes/index.tsx
@services/plan/src/routes/docs/index.tsx

T-009 - Create src/routes/docs/$.tsx

Create the catch-all doc page route: server loader resolves slug → page, client loader lazy-loads MDX, renders in DocsLayout.

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

Acceptance

serverLoader resolves URL slugs via source.getPage(), throws notFound() if missing
Returns { path, pageTree } (serialized nav tree)
clientLoader lazy-loads MDX via browserCollections.docs.createClientLoader
Renders DocsPage with DocsTitle, DocsDescription, DocsBody
MDX components include custom Mermaid component
Page component wraps in DocsLayout with baseOptions() and pageTree

Files

@services/plan/src/routes/docs/$.tsx

T-010 - Create src/routes/api/search.ts

Create the full-text search API endpoint at GET /api/search.

Status: completed
Priority: P1
Dependencies: T-007

Acceptance

Uses createFromSource(source, { language: 'english' })
Indexes: id, title, description, structuredData, url per page
Route registered at /api/search with GET handler

Files

@services/plan/src/routes/api/search.ts

T-011 - Create src/lib/source.ts and src/lib/layout.shared.tsx

Create the Fumadocs source loader and shared layout options.

Status: completed
Priority: P0
Dependencies: T-004

Acceptance

src/lib/source.ts exports source via loader({ baseUrl: '/docs', source: docs }) (current Fumadocs API)
src/lib/layout.shared.tsx exports baseOptions() returning { nav: { title: 'Atlas Plan' } }

Files

@services/plan/src/lib/source.ts
@services/plan/src/lib/layout.shared.tsx

T-012 - Create src/components/mermaid.tsx

Create the client-only Mermaid diagram renderer with beautiful-mermaid as preferred renderer and official mermaid as fallback.

Status: completed
Priority: P1
Dependencies: T-004

Acceptance

Component mounts only after hydration (avoids SSR mismatch)
Uses beautiful-mermaid for: graph, flowchart, stateDiagram, stateDiagram-v2, sequenceDiagram, classDiagram, erDiagram
Falls back to official mermaid for all other diagram types
Respects next-themes dark/light mode (github-dark / github-light themes)
SVG cache keyed by mode + chart content

Files

@services/plan/src/components/mermaid.tsx

Phase 4: Integration

Purpose: Wire up the workspace, update docs, and verify everything works

T-013 - Integration: bun install, AGENTS.md update, type-check

Run bun install to resolve all new catalog entries and workspace packages. Update AGENTS.md with the plan commit scope and NETWORK.yml policy. Verify type-check passes.

Status: completed
Priority: P0
Dependencies: T-001, T-002, T-003, T-004, T-005, T-006, T-007, T-008, T-009, T-010, T-011, T-012

Acceptance

bun install completes without errors
AGENTS.md mentions plan in the commit scopes list
AGENTS.md documents NETWORK.yml as source of truth for ports/domains
bun run test:type --filter @services/plan passes (or only has expected pre-install artifacts that clear after install)

Files

AGENTS.md
bun.lock

On this page