H1Document Instrument
A document-centric workflow engine for professionals who touch revenue.
H2What this is
Document Instrument is a document-first business system where a single living document acts as the control plane for real workflows.
It replaces fragmented dashboards, half-connected tools, and automation chaos with one authoritative surface that orchestrates:
- planning
- pricing
- offers
- orders
- campaigns
- exports
- publishing
The document is not a file.
It is an orchestrator.
H2Core principle
One document = one source of truth
- UI is minimal
- State lives on the server
- Mutations happen only via server actions
- Suspense coordinates partial re-rendering
- No client-side orchestration logic
- No silent side effects
Everything that matters is explicit, traceable, and reversible.
H2What this is NOT
Document Instrument is explicitly not:
- a dashboard app
- a generic CRM
- Zapier with AI
- a no-code workflow builder
- a cheap monthly productivity toy
If it starts to resemble any of these, it is out of scope.
H2Target users (v1)
- Independent professionals
- Consultants and operators
- Trip designers & experience sellers
- Small teams managing pricing, offers, and campaigns manually today
This is for people who touch revenue, not casual note-takers.
H2Core workflow
H3Start with a document
- User logs in
- Lands on a blank document canvas
- No menus by default
- Minimal navigation between documents
H3Compose deterministic sections
A document is composed of typed sections:
- text blocks
- planners (rows × columns)
- line items (prices, quantities, totals)
- trip builder
- metadata blocks
Each section:
- has a schema
- can be rendered or edited
- autosaves
- may trigger explicit server actions
H2Trigger real operations
From inside the document, the user can:
- generate a trip
- calculate pricing
- insert or overwrite line items
- promote Places → Contacts
- generate offers
- send emails
- export data
- publish to magazine
All triggers:
- go through server actions
- touch Prisma only in
actions/ - require explicit user confirmation
- call
revalidatePath/revalidateTag - rely on Suspense for refresh
No polling. No background magic.
H2Status-driven lifecycle
Entities evolve by status, not deletion:
- Draft → Proposed → Confirmed
- Orders and logs are permanent
- Everything else is revisable or disposable
- Revisions create new versions
This keeps the system honest and auditable.
H2Editor & Sidebar (non-negotiable)
- Editor = control plane
- Sidebar = instrument panel
Rules:
- Nothing complex lives inside the canvas
- All tools live in the sidebar
- Nothing runs without explicit user intent
H2AI (explicit and controlled)
AI is not the product.
AI is an assistive instrument.
H3Canonical AI tool pattern
The MLV Generator is the reference implementation.
All AI tools must follow:
- Sidebar UI
- typed form
- optional persona selector
- Server action
- structured input only
- Structured output
- JSON only
- schema-validated
- Preview
- no mutation yet
- Confirm
- explicit user action
- mutation + revalidation
If a tool skips a step, it is invalid.
H2Personas
Personas are prompt shapers, not agents.
They:
- do not own data
- do not run automations
- do not bypass schemas
Examples:
- Maestro de Ritmos (MLV / planning)
- Commercial Assistant (offers & pricing)
- Editorial Assistant (publishing tone)
- Operations Assistant (exports & integrations)
H2Integrations (v1 — tight scope)
Included:
- Google Places (prospecting)
- Email (manual send + logs)
- Google Calendar (export / invites)
- CSV / JSON exports
- Magazine publish (unlisted)
Explicitly not v1:
- Zapier-style mappings
- background automation
- webhooks
- generic CRM sync
H2Publishing (Magazine)
- One magazine per scope
- Publish:
- whole document, or
- individual sections
- Generates unlisted, shareable URLs
- Exportable as PDF
Magazine is a projection, not a fork.
The document remains the source of truth.
H2Architecture (locked)
app/(pages)// page.tsx → Server page (read-only orchestration) layout.tsx → Layout (client or server) components/ → Client UI (no data access) actions/ → Server authority (ONLY Prisma access) lib/ → Pure helpers (safe server + client) context/ → Client-only UI state types/ → Domain types api/route.ts → HTTP wrapper (external only)
Rules:
- Prisma access ONLY in
<entity>/actions/ - Client components never call API routes
- Server pages never mutate
- Server actions orchestrate mutations + revalidation
- API routes are integration surfaces, not app plumbing
H2Definition of Done (MLV)
MLV is reached when:
- a user can create a document and compose sections
- autosave works
- one sidebar tool works end-to-end (MLV Generator)
- trip builder produces pricing rows
- Places → Contact promotion works
- a manual email sequence can be sent with logs
- one export works (CSV or JSON)
- one magazine page is published (unlisted)
Stop there. Ship. Pilot.
H2Strategic positioning
Sell this as:
A professional document instrument
Not:
- AI software
- automation platform
- productivity app
Lead with:
- control
- safety
- explicit actions
- no dashboards
- no automation chaos
AI assists.
The document leads.
H2Status
- Specification: LOCKED
- Architecture: PROVEN
- Remaining work: execution, not discovery
This project is in a safe, near-completion phase.
Document Instrument — Control without chaos.
⸻