Joshfransix/atlas builder

[JoshFransix]

feat: atlas-builder, glossary-driven Solana project scaffolder

What this adds

Atlas Builder turns a plain-English project description into a structured Solana/Anchor scaffold — driven entirely by @stbr/solana-glossary term data.

Two surfaces:

• atlas-builder CLI: describe your project, get concepts + architecture + folder tree
• Web UI at apps/atlas-builder/: live three-panel interface (Concepts / Architecture / Structure)

---

How it works

User input
   ↓
detectIntent()         - matches input against 12 known Solana project patterns
   ↓
resolveConcepts()      - maps each intent to real GlossaryTerm objects via getTerm() + searchTerms()
   ↓
expandConcepts()       - optionally follows `related` links one level deep (--expand)
   ↓
generateArchitecture() - derives { components, flows, notes } from concept categories + term IDs
   ↓
generateStructure()    - produces an Anchor-ready folder tree from the architecture

The 12 supported intents: escrow, staking, nft, token, defi, dao, game, marketplace, bridge, oracle, lending, wallet.

---

SDK integration

All pipeline functions are exported from @stbr/solana-glossary:

import { buildProject } from "@stbr/solana-glossary";

const result = buildProject("escrow program with PDA vaults", { expand: true, lang: "pt" });
// result.concepts     → GlossaryTerm[]
// result.architecture → { components[], flows[], notes[] }
// result.structure    → folder tree string

The lang option (en / es / pt) passes through the SDK's i18n layer so all concept names and definitions are returned in the target language.

---

Files added

src/builder/
  intentMap.ts
  detectIntent.ts
  resolveConcepts.ts
  expandConcepts.ts
  generateArchitecture.ts
  generateStructure.ts
  builder.ts

src/cli/atlas-builder.ts

apps/atlas-builder/
  app/page.tsx
  app/layout.tsx
  app/globals.css
  components/ConceptsPanel.tsx
  components/ArchitecturePanel.tsx
  components/StructurePanel.tsx
  lib/builder.ts
  README.md

src/index.ts - builder exports appended
package.json - bin.atlas-builder + build entry added

---

CLI demo

npm run build && npm link
atlas-builder "build escrow program" --expand

Concepts:
  - Program Derived Address [programming-model]
  - Account [programming-model]
  - Instruction [programming-model]
  - Transaction [core-protocol]
  - Lamport [core-protocol]
  ...

Architecture:
  Components:
    - Program logic
    - On-chain program
  Flows:
    - Client → RPC → Program → Account read/write
    - Instruction → derive PDA → validate seeds → mutate state
  Notes:
    - PDAs require deterministic seed derivation and bump storage

Structure:
/program
  /src
    /instructions
    /state
    /errors
  Cargo.toml
/tests
  /integration
/scripts
  deploy.ts

---

Checklist

• npm test — 12/12 passing
• tsc --noEmit in repo root — 0 errors
• tsc --noEmit in apps/atlas-builder — 0 errors
• CLI smoke-tested with npx tsx src/cli/atlas-builder.ts
• Uses @stbr/solana-glossary SDK exclusively (no third-party AI/LLM deps)
• i18n support via --lang=pt / --lang=es