Atlas

A self-hostable engineering and web-ops dashboard that measures your site and your repo, and keeps the results itself.

Atlas is a drag-to-arrange canvas of telemetry cards. It is not a BI viewer you point at tables you already have: it ships its own collectors — Lighthouse and Core Web Vitals, SEO audits, region latency probes, repo metrics, releases, server errors, real-user monitoring — and owns the schema they write to. Point it at any Postgres, run one command, and the cards fill in.

Status: v0.1.0. The Next.js application, PostgreSQL storage, authentication, and generic card/collector framework are implemented and tested. The public GitHub Pages canvas uses sample data. Follow the deployment instructions for source and Docker installation.

Why it exists

• It measures, it doesn't just display. Every card has a collector behind it. pnpm collect region-latency writes rows; the card reads them. No glue.
• A card is one folder. cards/<id>/ holds the component, dataset query, collector and explainer. Register its metadata, view and server definition; the existing generic routes handle it. See the card contract.
• Zero keys on day one. Region latency, SEO audits and releases need no API keys. Configure the monitored site/repository, run pnpm run setup, then run the collectors. Collection time and availability depend on each provider.
• You own the data. One Postgres schema (default atlas), plain SQL, no ORM, no vendor. DROP SCHEMA atlas CASCADE is a clean uninstall.

Run the website

The product website and interactive demo live in site/. Build and serve them:

pnpm install --frozen-lockfile
pnpm build:pages
python3 -m http.server 4175 --directory dist/pages

Open http://localhost:4175 for the product overview and http://localhost:4175/demo/ for the working dashboard with twenty-one sample cards. The demo needs no account or database. The older /preview/ URL remains supported, and the original canvas is preserved at /canvas/ with its saved browser layouts.

Run the application

Use Node 22.6+ and the pnpm version declared in package.json:

pnpm install --frozen-lockfile
cp .env.example .env.local
# Configure your PostgreSQL URL, monitored site and authentication secrets.
pnpm run setup
pnpm dev

Open http://127.0.0.1:3000. The setup screen explains incomplete configuration. The development server binds to loopback. For production, configure password or trusted-proxy authentication and the canonical dashboard origin before building; open authentication refuses production access. See authentication and setup, storage implementation, and card development.

Website · Shared design · Agora

Dashboard controls

• New dashboard creates and selects an independent layout with the sample cards.
• Rename changes the active dashboard name without changing its layout.
• Edit layout exposes Move handles, size controls, and resize corners. On a desktop, cards move on a 12-column grid; occupied cards move down to make room.
• Drag a Move handle or use its arrow keys. The ↑ / ↓ buttons change reading order without dragging. On small screens, cards form a single column and dragging changes their order; desktop widths are retained.
• Drag a resize corner or use its arrow keys. Width/height menus provide the same controls without dragging; mobile layouts use full available width.
• Undo (also Ctrl/⌘+Z while editing) reverses the last change. Tidy layout fills empty spaces. Done hides editing controls.

Layouts, names, and the active tab save to this browser's local storage. They survive reloads on the same origin but do not sync across devices or users. Storage errors are shown in the toolbar; in that case edits remain in memory. Unreadable old saves are preserved rather than overwritten. The storage adapter in site/dashboard/storage.mjs is separate from the canvas state model.

Cards

group	what it shows	collector
Performance	Lighthouse scores, Core Web Vitals per route	lighthouse
Real users	field LCP / INP / CLS from a tiny beacon	push-ingested
SEO	per-page audit findings and score history	seo-audit
Region latency	TTFB from a dozen regions, via Globalping	region-latency
Code quality	duplication, complexity, dependency health	repo-metrics
Releases	deploy cadence and what shipped when	releases
Errors	server error rate and top messages	push-ingested
AI usage	token spend across coding-agent CLIs	ai-usage (opt-in)
Anomalies	what changed, deep-linked to the card that saw it	derived

Cards you don't need are one line in atlas.config.ts to disable. A card whose requirements aren't met stays on the grid and says why, rather than vanishing.

Charts to add

Chart types Atlas does not draw yet, taken from a set of dashboard UI blocks. Atlas already has bar, stacked area, line, donut, segmented, ranking, progress, gauge, grouped bar, Sankey, weekday × hour heatmap, treemap and bubble charts.

Added: the Gantt chart, as a lane timeline (components/analytics/lane-timeline.tsx, laid out by lib/charts/timeline-layout.ts). It groups items into lanes, packs overlapping bars into rows, marks milestones inside a bar, links an item to the one it followed, and has a today line and zoom (fit, 30 days, 90 days, a year) with panning. Releases uses it first: a lane per major version, a bar per release line. It does not show owners, and it zooms by span rather than by a day/week/month scale.

chart	what it shows	where it fits
Dot-matrix world map	locations as glowing points with route arcs, coloured by health	Region latency: probes by location
Latency histogram	distribution with p50 / p95 / p99 markers, a shaded SLO band, yesterday as a dashed outline, linear/log scale	Region latency, Real users
Trace waterfall	a span tree with nested timing bars and a minimap	a request's server timings. Partly covered by the lane timeline, which already draws timing bars, packs them into rows and links them; the span tree and minimap are still to do
Flame graph	an icicle CPU profile with function search	a profiled render
Service topology	services as nodes, traffic as animated links: width is requests per second, colour is error rate	Errors, by service
Cohort retention heatmap	signup cohorts × months since signup, with a weighted-average row	Real users, newsletter signups
Bullet chart	actual against target over poor → good bands	Lighthouse and Core Web Vitals budgets
A/B result	confidence-interval plot per variant, plus cumulative uplift as a band that narrows over time	experiments, anomalies
Host grid heatmap	one square per host, grouped by region, coloured by load	Region latency, repo or server health

Configuration

atlas.config.ts at the repo root: your site URL, which cards are enabled, and any overrides. The database is one variable, DATABASE_URL.

Security

Three auth adapters are available: loopback development only, a shared password, and a trusted identity header plus a proxy secret. Browser sessions require CSRF validation for writes. Optional bearer credentials permit collection only. See authentication and security policy.

Design and development

The site imports @aisocratic/design from the Stoa repository. site/vendor/design.css is an exact copy of the generated dist/css/site.css, including tokens, typography, shared header, mobile menu, hero, buttons, and footer. Atlas-specific preview and content styles live in site/styles.css.

The package version and SHA-256 are recorded in site/vendor/design.json. Refresh an unpublished local build and verify the checked-in dependency:

# In a Stoa checkout: pnpm install && pnpm build
node site/scripts/sync-design.mjs ../stoa
node site/scripts/sync-design.mjs --check
node --test tests/dashboard.test.mjs

For a published release, use node site/scripts/sync-design.mjs --version X.Y.Z. The checked-in stylesheet keeps a clean clone independent of package availability and sibling checkouts. Commit the stylesheet and metadata together when updating.

Browser regression tests use Playwright as a development-only dependency:

pnpm install --frozen-lockfile
pnpm exec playwright install chromium
pnpm test:e2e

The suite starts its own static server and covers desktop and mobile input. To use an installed Chrome instead of downloading Chromium, run PLAYWRIGHT_CHANNEL=chrome pnpm test:e2e.

Before a pull request, run the integrity check, build and serve dist/pages/, and check desktop and mobile layouts, navigation, and the dark → light → system theme cycle. The Pages workflow runs the canvas/state/storage tests, verifies design integrity, and deploys dist/pages/ when changes reach main. The tests cover independent boards, collision handling, resize bounds, keyboard/button ordering, persistence, and storage failures. Browser checks cover actual tab, dialog, drag, resize, theme, and mobile interactions. The application CI separately verifies real PostgreSQL storage, card execution, authentication and production browser workflows.

License

MIT © AI Socratic. The design system is @aisocratic/design. Fonts are Inter, Newsreader and JetBrains Mono under the SIL Open Font License 1.1, loaded by the website.

Application demo

For an authenticated PostgreSQL-backed workspace with all nine synthetic cards, see Demo setup and isolation. Enable ATLAS_DEMO=true and run pnpm seed; fixtures and dashboard changes stay in a reserved demo schema.

Analytics design preview

Open the interactive analytics preview. For local development, run pnpm dev --port 3015 and open http://127.0.0.1:3015/preview. pnpm build:pages bundles the same components into dist/pages/ for GitHub Pages. This standalone preview needs no database or authentication and contains only synthetic fixtures. It combines AI Socratic admin card styling with Codex-style stacked usage bars and stacked area charts for turns, plugin calls, and skills. Date ranges, daily/weekly aggregation, clickable legends, model/surface switching, favourites, expanded charts, and layout editing work locally. Card order, widths, and favourites persist in browser storage; the production telemetry workspace at / continues to use its existing authenticated database routes.

Check fixture aggregation with pnpm exec tsx --test tests/analytics/*.test.ts.

The preview also includes Community Roles and Working Status donuts, Devices share bars, ranked Industries and Newsletter Sources, Backlog progress bars, Lighthouse score rings, grouped Signups, Server Errors, and Luma referral metrics. Community and backlog breakdowns use the latest snapshot inside the selected range; activity cards sum the range. New cards append to previously saved layouts.

The analytics preview uses Stoa selectboxes and compact chart value tooltips. Edit mode provides a 12-column canvas with collision handling, edge/corner resize, Auto, Compact, Snap, Reset, and Undo (Ctrl/⌘+Z). Each category saves its own layout in this browser. Keyboard arrow keys operate focused move and resize handles.