Verbolus documentation¶
This documentation describes Verbolus as implemented and planned across its games, shared lexical platform, web application, data stores, and operating procedures.
This page is intended to be the curated documentation entry point. In the preserved export layout,
it remains doc/index.md and the repository overview remains README.md at the
export root. The destination MkDocs repository can select this page as its home or first navigation
item without moving either source file; that site's configuration remains external to this repository.
Snapshot represented here¶
This content snapshot includes the compact identity and storage redesign currently implemented on
the jm/string-repetition branch through commit a12ff3b. That redesign is not yet merged to
main or assumed to be deployed. In particular, the snapshot includes:
- value-based lexical identities and compact catalog metadata;
- structural Reverse Cross slot and entry identities in memory;
- Reverse Cross puzzle storage schema v2, with dual v1/v2 reads and v2 writes;
- Reverse Cross play storage schema v2, with dual v1/v2 reads and feature-gated v2 writes; and
- the decision not to compact Cosmos document keys without new operational evidence.
Documents use these lifecycle terms:
| Term | Meaning |
|---|---|
| Deployed | The behavior is intended to describe the production system. |
| Implemented on branch | The behavior exists in this repository snapshot but is not asserted to be merged or deployed. |
| Accepted | The decision governs implementation even if later rollout work remains. |
| Proposed | The design is available for review but is not an implementation commitment. |
| Deferred | Work has explicit conditions that must be met before it resumes. |
| Historical record | The document preserves implementation or validation context but is not a current system overview. |
When status matters operationally, verify the deployed revision and feature-flag state rather than inferring production state from a design document.
Choose a reading path¶
flowchart TD
Start[What do you need?]
Start -->|Understand the product| Games[Game specifications]
Start -->|Understand the system| Architecture[Architecture and decisions]
Start -->|Understand direction| Strategy[Strategy and roadmaps]
Start -->|Operate production| Operations[Runbooks]
Start -->|Implement planned work| Plans[Implementation plans]
Start -->|Reproduce evidence| Validation[Validation and measurement]
Games --> LG[Letter Golf]
Games --> RC[Reverse Cross]
Architecture --> Lexical[Lexical platform]
Architecture --> Storage[Identity, memory, and persistence]
Strategy --> Platform[Platform roadmap]
Strategy --> Product[Product and commercial strategy]
Product and game specifications¶
These pages explain what Verbolus and its games are. Start here before reading implementation plans or storage details.
| Document | Audience | Role |
|---|---|---|
| Letter Golf | Product, design, engineering | Rules, scoring, modes, and product behavior for the deployed game. |
| Reverse Cross | Product, design, engineering | Rules, terminology, modes, and the high-level technical direction. |
| WordSpin | Product and game design | Historical/future game concept, not an active implementation commitment. |
| Game specification template | Documentation authors | Standard structure for future game specifications. |
Strategy and roadmaps¶
These pages answer why the product is moving in a direction, what has been decided, and what work remains. They should not be used as low-level API or operator instructions.
| Document | Status | Role |
|---|---|---|
| Platform roadmap | Active roadmap | Cross-platform sequencing, dependencies, and delivery status. |
| Reverse Cross roadmap | Active roadmap | Detailed Reverse Cross phases and exit criteria. |
| Engagement platform plan | Proposed strategy | Accounts, groups, notifications, events, and membership direction. |
| Advertising strategy | Accepted staged strategy | Placement principles, vendor progression, and product guardrails. |
| Accounts and subscriptions plan | Proposed architecture | Identity, account merge, sessions, subscriptions, and payment boundaries. |
Architecture and engineering reference¶
These are durable explanations of boundaries, representations, algorithms, and accepted technical decisions. They describe this branch snapshot unless a page says otherwise.
| Document | Status | Role |
|---|---|---|
| Lexical and game architecture | Implemented on branch | Ownership and data flow from sources through game-specific indexes. |
| Lexical algorithmic complexity | Implemented reference | Time and space complexity of catalog, views, and game algorithms. |
| Data layout and persistence | Implemented on branch | Current identity scopes, measured memory layout, versioned payloads, Cosmos keys, and retention. |
| Compact identities and storage | Implementation and decision record | Per-phase measurements, compatibility evidence, decisions, and deferred work. |
| Reverse Cross evaluator design | Foundations implemented | Quality metrics, deterministic evaluation, and calibration boundaries. |
| Reverse Cross generation ADR | Accepted | Generation, solution-witness, replay, and resource-bound decisions. |
| Lexical catalog cold-start plan | Deferred | Compiled-artifact option and evidence required to reopen it. |
| LLM content enrichment | Proposed | Offline enrichment and editorial workflow boundaries. |
Implementation plans and delivery records¶
These pages are useful to engineers carrying out or reviewing a particular body of work. A completed handoff may remain valuable as a decision and traceability record, but it is not the best entry point for understanding the whole system.
| Document | Role |
|---|---|
| Accounts identity UX implementation plan | Sign-in, guest promotion, merge, and recovery interaction design. |
| Brand and navigation rollout plan | Visual identity and navigation rollout sequence. |
| Group member social UI plan | Group standings and member-detail interaction design. |
| Stats sharing implementation handoff | Detailed implementation and verification record for stats-sharing work. |
Operations and compliance runbooks¶
These pages are procedural. Operators should follow prerequisites, preview steps, evidence requirements, and rollback guidance exactly rather than adapting strategy documents into commands.
| Document | Operator task |
|---|---|
| Account deletion runbook | Execute and verify resumable account erasure. |
| Expired account session recovery | Understand cookie lifetimes, sign-in recovery, and puzzle progress. |
| Feature-flag operator runbook | Change per-user or global Azure App Configuration feature state. |
| AdSense site-review runbook | Validate site-review readiness and resubmit safely. |
| Lexical memory analysis runbook | Capture and interpret catalog heap evidence. |
| Documentation export runbook | Export Markdown into the separately managed documentation site. |
Validation and measurement records¶
These pages define repeatable evidence or preserve a focused validation plan. They are supporting material rather than primary architecture.
| Document | Status | Role |
|---|---|---|
| Phase 4 pool measurement plan | Active evidence plan | Latency, throughput, freshness, and capacity thresholds for puzzle generation. |
| Frontend Vitest test plan | Partly implemented record | Frontend unit/component testing priorities and rollout. |
| God View date-browse test plan | Active manual checklist | Browser scenarios not yet represented by the Playwright suite. |
How the technical references fit together¶
flowchart LR
Sources[Lexical sources] --> Catalog[Canonical catalog snapshot]
Catalog --> Views[Eligibility views]
Views --> LGIndex[Letter Golf index]
Views --> RCIndex[Reverse Cross fill index]
RCIndex --> Generator[Bounded puzzle generator]
Generator --> Domain[Structural puzzle domain]
Domain --> PuzzleV2[Puzzle schema v2]
Domain --> PlayRuntime[Textual runtime placements]
PlayRuntime --> PlayV1[Play schema v1]
PlayRuntime --> PlayV2[Play schema v2]
LexArch[Lexical and game architecture] -. explains .-> Catalog
Complexity[Algorithmic complexity] -. quantifies .-> Views
Layout[Data layout and persistence] -. specifies .-> PuzzleV2
Compact[Compact identities and storage] -. records evidence .-> Layout
Evaluator[Evaluator design] -. assesses .-> Generator
ADR[Generation ADR] -. constrains .-> Generator
For implementation details, follow links from the architecture page into the relevant design, decision, measurement, or runbook. For current delivery priorities, return to the roadmaps rather than treating an older implementation handoff as an active plan.