atlas-tx-bootstrap

name	atlas-tx-bootstrap
description	Bootstrap the Atlas TX project from zero: create public GitHub repo, scaffold Next.js app, lock MVP Texas datasets, add county normalization, and add initial Socrata adapter helpers with TDD.
version	1.0.0
author	Hermes Agent
metadata	{"hermes":{"tags":["atlas-tx","texas-open-data","nextjs","github","vitest","socrata","county-normalization"]}}

Atlas TX bootstrap

Use when working on ~/Projects/atlas-tx or recreating the same setup elsewhere.

What this establishes

• Public GitHub repo
• Next.js 16 + TypeScript app scaffold
• README and implementation plan
• MVP dataset registry for Texas county intelligence
• County normalization helpers
• Initial Texas Open Data / Socrata adapter helpers
• Vitest test harness for utility-layer TDD

Proven workflow

1. Create repo first

• Repo name used: atlas-tx
• Public description:
  • Atlas TX - Texas county intelligence for environment, social strain, and local fiscal capacity
• Command pattern:
  • gh repo create sbauwow/atlas-tx --public --description "..."

2. Scaffold app locally

• Create under ~/Projects/atlas-tx
• Use Next app router + TS + npm:
  • npx create-next-app@latest /home/stathis/Projects/atlas-tx --ts --eslint --app --src-dir --use-npm --import-alias '@/*' --yes
• Add origin and push after first meaningful commit.

3. Replace boilerplate immediately

• Rewrite README.md with:
  • product framing
  • MVP dataset list
  • architecture sections
  • constraints / caveats
• Add plan doc under:
  • docs/plans/YYYY-MM-DD-initial-plan.md
• Replace default landing page and metadata in:
  • src/app/page.tsx
  • src/app/layout.tsx
• Add simple health route:
  • src/app/api/health/route.ts

4. Lock MVP datasets in code

• Create src/lib/mvp-datasets.ts
• Include at least these IDs:
  • 7fq8-wig2 TCEQ Water Quality Individual Permits Active/Pending
  • hr84-s96f Texas Water Districts
  • waxz-c9q5 CPI Completed Abuse/Neglect Investigations by County and Region FY2016-FY2025
  • u3nh-2phm Local Government Debt Report (HB 1378) FY 2023
  • ctj5-pypw County Returns
  • tmhs-ahbh Sales Tax Allocation, Tax Rates
  • xdwx-843n Debt Outstanding by Local Government (external/href)
  • djkj-euda Local Debt Bond Election Results (external/href)
• Model each entry with:
  • id
  • name
  • category
  • publisher
  • summary
  • keyFields
  • useCase
  • accessType (dataset or external)

5. Add MCP + skill placeholders early

• Create:
  • packages/mcp-server/package.json
  • packages/mcp-server/src/index.js
  • packages/mcp-server/README.md
  • skills/atlas-tx/SKILL.md
• Keep these small; goal is visible technical direction, not full implementation yet.

Utility layer that worked

County normalization

Create src/lib/counties.ts with:

• normalizeCountyName(input)
• countySlug(input)
• sameCounty(left, right)

Normalization findings:

• treat missing suffix as county name (Travis -> Travis County)
• normalize case
• normalize st. / st to saint
• strip punctuation before slugging
• stable slug format:
  • lowercase
  • non-alnum -> -
  • trim edges

Texas Open Data adapters

Create src/lib/texas-open-data.ts with:

• getDatasetById(id)
• getTabularDatasetIds()
• datasetResourceUrl(id)
• buildCountyDatasetUrl(id, county)

Important findings:

• Socrata tabular base:
  • https://data.texas.gov/resource/<id>.json
• Only build resource URLs for accessType === 'dataset'
• href assets like Bond Review Board microsite pages must return undefined from datasetResourceUrl
• County field names differ by dataset; hardcode a map initially:
  • 7fq8-wig2 -> facility_county
  • hr84-s96f -> county
  • waxz-c9q5 -> county
  • ctj5-pypw -> county_name
  • tmhs-ahbh -> county_name
• For initial filtering, uppercase the county base name without County suffix (Travis County -> TRAVIS)

Test setup that worked

1. Install Vitest

• npm install -D vitest

2. Add script

• in package.json:
  • "test": "vitest run"

3. Add vitest.config.ts

• Alias @ -> src
• Use environment: 'node'

4. Initial tests

• tests/county.test.ts
• tests/texas-open-data.test.ts
• tests/texas-open-data-fetch.test.ts

5. TDD sequence that worked

• Write tests first
• Observe failure due to missing modules/functions
• Implement smallest utility functions
• Re-run focused tests
• Then run:
  • npm run lint
  • npm run build

Verification commands

• npm test -- tests/county.test.ts tests/texas-open-data.test.ts tests/texas-open-data-fetch.test.ts
• npm run lint
• npm run build
• For local API health after npm run dev:
  • if 3000 is occupied, Next may move to 3001
  • verify /api/health on actual port

Pitfalls discovered

• create-next-app can infer the wrong workspace root when multiple package-lock.json files exist up-tree.
• Fix with next.config.ts:
  • set turbopack.root to project directory.
• Tooling quirk:
  • targeted patch tool syntax-check noise may be broader than actual project build state; trust npm run build over generic patch-time TS noise.
• Local port 3000 may already be owned by another Express app; when verifying health, probe 3001 if needed.

Good next slice after bootstrap

1. county comparison service
2. dataset fetch adapters for the 6 core tabular datasets
3. /api/compare/counties
4. compare UI cards
5. MCP tool contracts