Documentation Roadmap

Last Updated: January 1, 2026

Excellent work on compiling such a thorough set of documentation. The core "Define, Execute, Store" model (Workflow Builder, Sessions, Sheets) is now exceptionally well-mapped.

Based on the provided context, the remaining areas to map fall into three main categories:

1. Supporting Product Features & User Experience
2. Deeper Technical Systems & Architecture
3. Developer Operations & Lifecycle

---

1. Supporting Product Features & User Experience

While the core functionality is covered, several surrounding features and user journeys are mentioned but don't have dedicated architecture docs.

Workspace Administration & Billing

How do users manage their group? This is a critical area for team-based usage.

Key Questions:

• How are members invited, removed, and their roles (admin, member) managed?
• What settings are available at the workspace level (branding, security, API keys)?
• How would a billing/subscription model integrate with the groups table?

Suggested Doc: WORKSPACE_ADMINISTRATION.md

Onboarding & User Lifecycle

The initial user experience is crucial for adoption.

Key Questions:

• What is the flow for a brand new user signing up?
• What happens when a user is invited to a workspace or a specific session?
• Are there welcome emails or product tours?

Suggested Doc: USER_ONBOARDING.md

Search & Discovery

How do users find what they're looking for across a potentially large workspace?

Key Questions:

• What entities are searchable (workflows, sessions, sheets)?
• What is the underlying search technology (e.g., simple SQL LIKE, a dedicated search index)?
• How does the /api/home/* endpoint family support this?

Suggested Doc: SEARCH_AND_DISCOVERY.md

---

2. Deeper Technical Systems & Architecture

Several complex technical systems are used throughout the app but aren't explained in a dedicated document.

Real-time & Collaboration Layer (Ably)

This is mentioned in Sessions documentation but is a critical system deserving its own deep dive.

Key Questions:

• What is the full channel structure (e.g., per-session, per-stage, per-workspace)?
• What specific event messages are passed?
• How is presence used beyond the session graph?
• How does the useChannel hook manage query invalidation to keep clients in sync?

Suggested Doc: REALTIME_ARCHITECTURE.md

Background Jobs & Scheduling (Inngest)

The /api/inngest endpoint and scheduled_starts table imply a significant amount of asynchronous processing.

Key Questions:

• What specific jobs are handled by Inngest (e.g., sending notifications, processing scheduled starts, cleanup tasks)?
• What are the triggers for these jobs?
• What is the retry and failure logic?

Suggested Doc: BACKGROUND_JOBS.md

State Management Philosophy (Zustand & React Query)

The docs mention useSessionStore and React Query, but the overall strategy isn't codified.

Key Questions:

• When should a developer use Zustand vs. React Query vs. local component state?
• What are the responsibilities of each store (useUIStore, useWorkflowBuilderStore, useCommonStore)?

Suggested Doc: CLIENT_STATE_MANAGEMENT.md

Authorization & Permissions (Abilities)

The abilities directory and validateUser function hint at the security model, but it's not fully explained.

Key Questions:

• How is the memberships role (admin vs member) used to control access?
• How are abilities defined for actions like "can delete workflow" or "can manage sheet"?
• How does this system interact with the session-level permissions (can_write, can_progress)?

Suggested Doc: AUTHORIZATION_MODEL.md

---

3. Developer Operations & Lifecycle

This category covers the "how we build" aspects that are crucial for team velocity and stability.

Testing Strategy

The __tests__ and __e2es__ directories exist, but the philosophy is not documented.

Key Questions:

• What is the testing pyramid for this project (unit, integration, e2e)?
• What are the primary tools (e.g., Jest, React Testing Library, Playwright/Cypress)?
• Where should new tests be added for a new feature?
• Are there conventions for mocking data or services?

Suggested Doc: TESTING_STRATEGY.md

Deployment & CI/CD

How does code get from a developer's machine to production?

Key Questions:

• What do the .github/workflows do?
• What is the branching strategy (e.g., GitFlow, trunk-based)?
• What environments exist (dev, staging, prod)?
• How are database migrations handled during deployment?

Suggested Doc: DEPLOYMENT_PROCESS.md

Local Development Setup

A crucial document for onboarding new developers.

Key Questions:

• What are the prerequisites (Node version, DB, etc.)?
• How does one set up environment variables?
• Is there a seed script to populate a local database with test data?

Suggested Doc: A CONTRIBUTING.md or a more detailed DEVELOPMENT_SETUP.md

---

Summary

You have a fantastic foundation. Mapping these remaining areas would provide a complete, 360-degree view of the product, its architecture, and the development process.

---

Related Documentation