Atlas County Maps (ChatGPT App)

Current product (2026-09-10): read-only US Census atlas for ChatGPT. Start at CHATGPT.md, then AGENTS.md and docs/STATUS.md. Compiled wiki: llm-wiki/wiki/index.md. GitHub map: GITHUB.md.

The copy below is historical (voxel plugin era). docs/NORTH_FACE.md is not current product law. Do not implement from it.

Product law: AGENTS.md. Historical note only: docs/NORTH_FACE.md.

Atlas is a ChatGPT plugin (Apps SDK / MCP + widget) for high-quality voxel county maps and session notes. The playable proof is Riverside / Eastvale: pan, inspect places, pin, and leave notes that stay in this chat. Other US counties open as honest generated maps with real Census town names. Clawd / Scout / campaign planning is parked for later. Map-first, not a dashboard.

Hero prompts:

Open Riverside County and show the Eastvale map.
Show me Miami-Dade County.

The current engineering route is Alpha-first:

• Curated county JSON.

• Typed service contracts.

• PixiJS VoxelScene renderer with SVG fallback.

• Google Maps behind GeoDataAdapter, not as the main renderer.

• Apps SDK/MCP tools as the ChatGPT entrypoint.

This repo already has a lean starter for the OpenAI Apps SDK pattern:

• A TypeScript MCP server exposed at /mcp.

• A separate React widget bundle rendered inside ChatGPT.

• The MCP Apps bridge for iframe communication.

• A decoupled data tool and render tool, so the model can reason over structured data before mounting UI.

This repo is intentionally not a generic SaaS shell. The current root server/ and web/ starter is a temporary Apps SDK sandbox; the Atlas monorepo skeleton now lives under apps/ and packages/.

Tooling

Use pnpm. On this machine, global npm fails under walk-up-path, so the scripts are written around pnpm and Corepack.

Required:

• Node.js 18 or newer. Current local check found Node v24.16.0.

• pnpm. Current local check found pnpm 11.7.0.

• Git.

No OpenAI API key is required for this local MCP app scaffold. ChatGPT connects to the /mcp endpoint through developer mode and a public HTTPS tunnel or deployment.

Related MCP server: civic-library-mcp

Commands

pnpm install
pnpm env:check
pnpm typecheck:workspaces
pnpm build
pnpm verify:mcp
pnpm dev

The dev server listens on:

• http://localhost:8787/ for a plain health page.

• http://localhost:8787/preview for the local widget preview.

• http://localhost:8787/mcp for ChatGPT, MCP Inspector, or a tunnel.

pnpm verify:mcp is a client smoke for a running MCP server. By default it checks http://127.0.0.1:8787/mcp; set ATLAS_MCP_URL to verify another local, tunnel, or Railway endpoint.

To test with MCP Inspector:

pnpm inspect

To connect from ChatGPT during development, expose the local server with a tunnel such as ngrok:

ngrok http 8787

Then create a ChatGPT connector in developer mode with the HTTPS URL ending in /mcp.

Structure

engineering-prompt-pack/ preserved source copy of the engineering prompt pack
prompt-pack/             preserved source copy of the first Atlas prompt pack
prompts/                 active Codex prompt sequence
docs/                    product and engineering route docs
plugins/                 Atlas daemon skill scaffold
data/county_packs/       curated county data
assets/                  asset prompts and placeholders
apps/widget/             Vite + React placeholder widget shell
apps/web/                placeholder web shell
packages/config/         shared constants placeholder
packages/core/           core contracts placeholder
packages/geo/            geo adapter placeholder
packages/mcp/            MCP layer placeholder
packages/assets/         asset package placeholder
server/
  src/index.ts        MCP server, tools, resources, HTTP endpoint
web/
  src/                React widget and MCP Apps bridge helpers
  dist/               Generated bundle, ignored by Git
scripts/
  build-web.mjs       esbuild widget build
  check-env.mjs       local environment sanity check
docs/
  apps-sdk-notes.md   distilled setup notes from the supplied docs

The official Apps SDK examples repo is cloned under .reference/openai-apps-sdk-examples for inspection and is intentionally ignored by Git.

Current Quest

Current implementation direction is defined by docs/NEXT_QUESTS.md and artifacts/current-update.json. README is an app overview, not the active quest authority.

The active ChatGPT county entrypoint is select_county for the Riverside/Eastvale playable slice:

• select_county

• ask_county_question

• render_voxel_county

• lookup_world_places

• preview_scout_drop

• preview_campaign_engine

• get_upgrade_options

The Railway backend is live at https://atlas-backend-production-e6fc.up.railway.app with Google geo configured server-side.

OpenAI Build Week extension

Atlas existed before the OpenAI Build Week submission period. The hackathon entry is the meaningful extension built from July 13 through July 18, 2026, not the earlier prototype.

Work added during the submission period includes:

• real 2024 U.S. Census town anchors for all 3,222 supported counties, with 13,797 named places and explicit generated-layout limits outside Riverside;

• a hardened seven-tool MCP submission contract, minimized provider results, public support/legal routes, and an exact positive/negative reviewer battery;

• stronger ChatGPT emulator fidelity, desktop/mobile visual audits, and a mobile place-sheet interaction fix;

• Redis scene-packet worker recovery, health/readiness behavior, release rollback gates, and the first successful production worker deployment; and

• a release-gated national Census geography bake for all supported counties, kept behind the atlasGeoBoard feature flag.

The main Codex build thread used GPT-5.6 and has session ID 019f687a-82d3-7df0-ac27-5b7ca38b099c. Codex helped audit the existing product, build and verify the national anchor pipeline, harden worker failure paths, tighten the MCP contract, run the release and browser proof ladders, and isolate the submission envelope. The human product decisions stayed explicit: keep Atlas map-first, submit the focused session-only County Scout, label generated geography honestly, and leave persistence, payments, and automated outreach out of the public entry.

The full Devpost copy, demo script, test prompts, and judging handoff are in docs/DEVPOST_BUILD_WEEK_SUBMISSION.md.

State Model

• Server or backend owns business data.

• Widget state owns ephemeral view behavior such as selected district/place, stickers, and notes.

• Durable cross-session state belongs in a backend storage layer once the product needs it.

• The widget can call ui/update-model-context when UI state should affect the model's next turn.

Avoid putting secrets, tokens, or private data in structuredContent, content, _meta, or widget state.