Workspace Map

This page is the directory-level map for /Users/laitsky/Developments/vela-labs. Every directory, every root file, and every planning artifact is documented here.

Top-Level Directories

Path	Type	What it contains	Why it matters
.planning/	Planning + ops	Requirements, roadmap, milestones, state tracking, phase artifacts, research, quick tasks, audits, workstreams, seeds, todos	Authoritative source of project truth — more current than root docs or repo READMEs
.github/	Automation	GitHub Actions workflows (CI, staging E2E, schema-diff checks)	Protects main branches, runs Playwright, validates webhook schemas
.claude/	Local assistant state	Claude-specific local support files and worktrees	Session continuity for Claude Code agents
internal-wiki/	Documentation site	This VitePress wiki — the navigable knowledge base for the workspace	Single source of narrative truth for investors, contributors, and future sessions
vela-protocol/	Product repo	Anchor programs (vela-protocol + vela-transfer-hook), Arcium circuits, LiteSVM tests, IDL, build artifacts	The billing primitive — mandate PDAs, stream mandates, pull approvals, credential minting
vela-sdk/	Product repo	TypeScript SDK (@vela/sdk), CLI, generated builds, IDL copies, PDAFactory, V1/V2 account types	Developer-facing API to the protocol — instruction builders, account derivation, webhook events
vela-dashboard/	Product repo	Merchant SPA + Hono Worker + D1 schema + Helius webhook handler + analytics	Merchant-facing product surface — plan creation, subscriber management, billing analytics
vela-admin/	Product repo	Internal admin SPA + Hono Worker (service-binding to dashboard)	Protocol team operations — monitoring, emergency controls, audit trail
vela-checkout/	Product repo	Hosted checkout app + payment links + invoice pages + session API	Public checkout at pay.velapay.com — wallet approval flow, Turnstile gating
vela-portal/	Product repo	Subscriber self-service portal	Subscriber management at portal.velapay.com — magic-link auth, plan switching, invoices
vela-web/	Product repo	Public landing page	velapay.com — value proposition, code snippets, developer CTAs
vela-docs/	Product repo	Developer documentation site	docs.velapay.com — 60 MDX pages, Starlight theme, SDK reference
vela-widget/	Product repo	Embedded checkout loader + iframe checkout app	Merchants embed <vela-pricing-table> or checkout widget on their pages
vela-webhook/	Product repo	@vela/webhook package — Zod-typed events, HMAC verifier, retry dispatcher	Typed webhook delivery for all Vela billing events
vela-synthetic/	Product repo	Cloudflare Cron Worker	15-min synthetic E2E check against devnet staging with paging on failure
scripts/	Utility	Helper scripts for development, deployment, and operations	Workspace-level tooling
docs/	Utility	Additional workspace-level documentation	Supporting docs outside the wiki
node_modules/	Dependency	Root-level Bun dependencies	Minimal root surface — mostly workspace tooling

Root-Level Strategy Documents

The workspace root contains a numbered research and strategy set that captures the project's founding context. These documents were written during the Colosseum hackathon preparation phase and remain directionally valid, though .planning/ holds more current execution truth.

File	Focus	When to consult it
01-vela-labs-brand.md	Naming system — Vela Labs (company), Vela Protocol (primitive), VelaPay (product). Establishes the naming convention used across all repos, docs, and marketing.	When naming decisions arise or brand consistency needs checking
02-privacy-first-subscription-billing-deep-dive.md	Core market and architecture thesis. Why subscription billing on Solana is unsolved, why privacy matters, and how Arcium fits. The founding technical document.	Understanding the original problem framing and technical reasoning
03-alternative-angles-privacy-subscription-billing.md	Alternative strategic framings and risk analysis. Explores different go-to-market angles, competitive responses, and failure modes.	Stress-testing the strategy or preparing for investor objections
04-product-blueprint-and-roadmap.md	Original product blueprint and roadmap framing. The aspirational phase structure that informed v1.0–v1.2 scope. Later milestones diverged from this doc.	Historical reference — compare original plans vs. actual execution
05-pm-strategy-and-hackathon-brief.md	ICP definition, GTM strategy, subscriber UX design, and agent narrative. The product management framing for the Colosseum submission.	Understanding target customer and go-to-market positioning
06-colosseum-competitive-research.md	Competitor teardown and hackathon strategy. Analyzed 10+ hackathon teams that attempted recurring payments on Solana and failed.	Investor prep — "why nobody else has solved this"
07-winning-strategy.md	Build and submission strategy with delivery sequencing. How to win the hackathon with scope management and demo strategy.	Historical reference for process lessons
08-vela-value.md	Deep value analysis and competitive correction pass. Updated post-hackathon with stronger competitive framing and market constraints.	Investor talking points — the "why Vela wins" narrative
09-hosted-checkout-billing-plan.md	Hosted checkout and billing plan design document. Scoped v1.5 features before milestone planning.	Understanding the checkout/portal/invoicing design decisions
10-future-vision-layer3-and-beyond.md	Future vision for Layer 3 revenue finance (MRR Oracle, lending, marketplace). The long-term product thesis beyond billing.	Investor prep — the "where this goes" story

Workspace Support Files

File	Purpose
package.json	Minimal root dependency surface — workspace-level tooling only
bun.lock	Shared Bun lockfile anchor for the workspace
AGENTS.md	Agent and workflow notes — shared coding guidelines for all AI agents
CLAUDE.md	Claude-specific project guidance — stack, constraints, conventions
docker-compose.staging.yml	Staging environment definition — Mailpit + wrangler trio for E2E tests
.gitignore	Workspace-level git exclusions
weekly-update-scripts.md	Weekly update generation scripts and templates
agentic-grant-application.md	Agentic Engineering Grant application content
agentic-grant-application.html	Rendered grant application HTML

.planning/ Directory Structure

The .planning/ directory is the authoritative source of project state. It is more current than root research docs, repo READMEs, or any individual code comment. When artifacts disagree, .planning/ wins.

Core State Files

Path	Role	Update frequency
PROJECT.md	Canonical current-state summary — what the project is, core value, current milestone, validated/active/out-of-scope requirements, key decisions, architecture, constraints, and evolution notes.	Updated at phase transitions and milestone boundaries
STATE.md	Current execution state — milestone, phase, plan progress, performance metrics, accumulated context, decisions, blockers, session continuity. Machine-readable frontmatter.	Updated after every plan execution
ROADMAP.md	Full milestone and phase history with expandable details. Every phase has goal, depends-on, requirements, success criteria, plan list, and completion date.	Updated at phase transitions
REQUIREMENTS.md	Product requirements organized by milestone with validation state (validated/active/out-of-scope). Traceability to phase and plan.	Updated at phase transitions
MILESTONES.md	Milestone completion log — shipped dates, phase/plan counts, key accomplishments per milestone.	Updated when milestones ship
RETROSPECTIVE.md	Process retrospective — what worked, what didn't, and process evolution across milestones.	Updated at milestone boundaries
config.json	GSD workflow configuration — model profile, workflow toggles.	Manual edits

Subdirectories

milestones/ — Per-milestone artifacts

Contains one subdirectory per milestone with its roadmap, audit results, and phase-specific artifacts:

milestones/
├── v1.0-ROADMAP.md          # Phase details for v1.0 Foundation
├── v1.0-MILESTONE-AUDIT.md  # Audit results
├── v1.1-ROADMAP.md
├── v1.2-ROADMAP.md
├── v1.5-MILESTONE-AUDIT.md  # Tech debt accepted
├── v1.8-MILESTONE-AUDIT.md  # v1.8 audit
└── ...

Consult when: Understanding what a specific milestone shipped, what gaps were found in audit, or what tech debt was accepted.

phases/ — Phase-specific plans and research

Contains plan artifacts organized by phase number. Each plan follows the NN-MM-PLAN.md naming convention:

phases/
├── 45-01-PLAN.md  # Streaming pre-gate: CU profile + slot inventory
├── 45-02-PLAN.md  # StreamMandate v1 struct + error codes
├── 46-01-PLAN.md  # Proration math foundation
├── 47-01-PLAN.md  # vela-webhook repo scaffold
└── ...

Also contains summary files (NN-SUMMARY.md) and design documents produced during execution.

Consult when: Understanding what a specific plan did, what files it changed, or what decisions were made during execution.

notes/ — Scope decisions and design documents

Freeform design notes and scope decisions that affect multiple plans:

notes/
├── v1.8-scope-decisions.md          # Why v1.8 has 3 phases instead of 5
├── v1.8-streaming-engine-design.md  # Streaming primitive design document
└── ...

Consult when: Understanding why a milestone is scoped the way it is, or why a particular design decision was made.

research/ — Supporting research

Reusable research artifacts consumed by planning:

research/
├── STACK.md         # Technology stack choices with rationale
├── ARCHITECTURE.md  # Architecture research and decisions
├── questions.md     # Open research questions
└── ...

Consult when: Understanding technology choices, version pinning rationale, or checking if a research question has been resolved.

quick/ — Quick-task execution records

Records of ad-hoc tasks that don't fit the phase/plan structure:

quick/
├── 260404-da6-PLAN.md      # Updated 08-vela-value.md
├── 260404-da6-SUMMARY.md
├── 260401-m6f-PLAN.md      # Keeper automation fixes
└── ...

Consult when: Checking if a specific fix or update was already done, or understanding ad-hoc changes.

seeds/ — Forward-looking ideas

Ideas with trigger conditions that should be surfaced at the right milestone:

seeds/
└── (future ideas awaiting trigger conditions)

Consult when: Planning a new milestone — check if any seeds should sprout.

todos/ — Pending work items

Todo items that haven't been promoted to a phase or plan yet:

todos/
└── (pending items)

Consult when: Starting a new session — check for pending work.

workstreams/ — Parallel workstream artifacts

Legacy workstream structure from earlier milestones. Some phases were executed inside workstreams before the current milestone-based model was adopted:

workstreams/
├── protocol-admin-dashboard/
└── ...

Consult when: Looking for phase artifacts from v1.2 era that may not be in phases/.

debug/ — Debug session state

Persistent debug context across sessions:

debug/
└── (debug state files)

Consult when: Resuming a debugging session or investigating a previously-seen issue.

tmp/ — Temporary working files

Scratch space for in-progress work. Contents are ephemeral.

What Changed Over Time

Repo Evolution

The workspace started as 5 repos and grew to 11 as the product surface expanded:

Phase	Repos	What was added
v1.0	5	vela-protocol, vela-sdk, vela-dashboard, vela-web, vela-docs
v1.1	6	+ vela-widget (checkout embed)
v1.2	7	+ vela-admin (internal ops)
v1.5	9	+ vela-checkout (hosted checkout), vela-portal (subscriber portal)
v1.8	11	+ vela-webhook (event SDK), vela-synthetic (E2E cron)

Planning Layer Evolution

• v1.0–v1.1: Planning was ad-hoc. Phase plans existed but milestone tracking was informal.
• v1.2: .planning/ became the authoritative source of project state. Workstreams were introduced for parallel phase execution.
• v1.3–v1.5: The quick-task lane (quick/) became a real execution path, not just a notes folder. Milestone audits (*MILESTONE-AUDIT.md) started capturing real gaps.
• v1.6–v1.7: Gap-closure phases became a recognized pattern (Phase 43, Phase 44). Artifact discipline (SUMMARY.md files, frontmatter) became enforced.
• v1.8: STATE.md gained machine-readable frontmatter. Phase merging (3 phases instead of 5) showed the planning layer can adapt scope without losing traceability.

Root Docs vs. Planning Layer

The root research docs (01–10) remain directionally aligned with the project vision. However:

• Root docs capture the why — market thesis, competitive landscape, brand identity, future vision.
• Planning layer captures the what and when — current state, requirements, decisions, execution history.
• When they disagree, planning layer wins for current state. Root docs are historical artifacts that informed early decisions.

Coverage Expectations

When updating this wiki or making project decisions, treat these as mandatory sources:

1. .planning/PROJECT.md — what the project is right now
2. .planning/STATE.md — where execution currently stands
3. .planning/ROADMAP.md — what has shipped and what's planned
4. .planning/REQUIREMENTS.md — what's validated, active, and out of scope
5. Root research docs (01–10) — why decisions were made originally
6. Each repo's README and manifest — what the code actually does

Git Statistics

Metric	Value
Total commits	529+
Active development days	~18 (2026-03-29 → 2026-04-17)
Average commits per day	~29
Milestones shipped	8 (v1.0–v1.7 complete, v1.8 verified)
Phases completed	47
Plans executed	206+
Total execution time	~36 hours of agent time