Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
documents
What it is
The core of the Documents feature: document CRUD, content storage, AI editing/tools, and file-type-specific services (spreadsheets, presentations, word docs, Illustrator/Photoshop files).
Start here
src/lib.rs: the hexagonal layout (domain/inbound/outbound) and which Cargo features gate each module.src/domain/service.rs+src/domain/ports.rs: orchestration and the ports adapters implement.src/domain/content.rs: document content storage model (markdown vs legacy Office formats, S3 locations).src/domain/docx_export.rs: DOCX export readiness policy; empty parts mean extraction is pending. Its entry point requires a checked document receipt.- Native Canvas creation follows markdown: metadata → canonical shared snapshot →
ready SyncService content, with compensation on failure.
create_canvasand CreateDocument with empty Canvas content need no browser initialization. DocumentToolContext::canvas_artifactsis the per-userenable-canvas-artifactsrollout, off unless a host wires it; the Canvas tools pass it to the worker.src/domain/canvas.rs: permission-scoped Canvas read/render/edit workflows, native type checks, actor-bearing tokens, AI admission and per-model metering.ReadCanvas/RenderCanvasare view-scoped;ApplyCanvasEditsapplies precise revision-checked SDK batches without a nested model, whileEditCanvasdelegates design work. Both use edit receipts and live scene deltas, never whole-file saves. Render output includes native media plus an immutable revision, crop/object mapping and actual DOM text bounds.src/domain/word_document.rs: Word tools read and edit the DOCX live copy through the editing worker. A DOCX nobody has opened yet is seeded first from its stored parts (S3DocumentFiles), in the editor's exact Loro shape (word_document/seed.rs, mirroring the webwriteCollabState); keep the two in step.src/inbound/toolset.rs: one submodule per AI document tool (create_document,edit_document,word_document,spreadsheet,presentation, ...).src/inbound/axum_router.rs: the HTTP surface;axum_router/get_text.rsserves/text-contentthroughsrc/domain/text.rs. Native Markdown comes from live collaborative storage, not the legacy S3 export.src/domain/ai_edit.rs: SDK editing of markdown documents and tasks by instructions.POST /{id}/ai-editruns EditDocument'sAiEditingService(admission, models, metering) with a token minted like EditDocument's: 422edit_refusedis the worker's clarification, 502edit_failedmay have partly applied, and a client disconnect drops the worker call (never spawn it).axum_router/presentation.rs,word_document.rs,design_files.rs: the presentation, Word, design, Photoshop and Illustrator tools over HTTP (/{id}/presentation,/word,/design,/photoshop,/illustrator), calling the same domain services with the same receipts. Word routes need an acting user; a bot caller's id rides in the worker token as the actor. Caller-fixable failures (PresentationError,WordDocumentRejected, the readers' errors) are 400s.axum_router/upload_file.rs:POST /uploadtakes a file's raw bytes (25 MiB) and runs UploadFile'sDocumentCreator::upload_file, minting the project receipt from the caller like the tool. It exists for clients that cannot PUT to presigned storage URLs, such as code mode's sandbox.
Scope
- Copying a legacy Canvas preserves its JSON seed and live sync room. Native Canvas copies use the room and retain the SyncService content location. Failed copies compensate destination storage and sync artifacts before removing the new document rows, logging cleanup failures independently.
- Owns: document lifecycle (create/rename/purge/upgrade), content storage and markdown backfill, comments, AI-editing tools, and file-type domain services (spreadsheet, presentation, word, illustrator, photoshop).
- Not here: realtime collaborative sync of document content → sync-service;
the lexical markdown node/editor implementation →
packages/lexical-core; Discussion comments, replies and thread state on any entity → themessagestoolset (this crate keeps onlyCommentOnText, the inline comment that places a mark).
Boundaries
- Depends on (feature-gated):
entity_access/entity_registry(permissions),ai_engine/ai_toolset/ai_billing/ai_usage(AI tools),pptx_engine/psd_engine(file formats),lexical_client(sync-service calls),comms_db_client(create/purge adapters),macro_db_client(purge/backfill). - Used by:
ai_tools,agent_harness,webhook,soup_realtime,memory,projects,skills,github— this crate's service and toolset are widely reused; check callers before changing a port signature.
Recipes
- Add an AI document tool: new module under
src/inbound/toolset/→ wire it intosrc/inbound/toolset.rs→ register it whereai_tools/crates/ai_toolsassembles the toolset. - Add a document route:
src/domain/service.rs(new domain method) →src/inbound/axum_router.rs→src/domain/ports.rsif it needs a new outbound capability. - Create a document from a Notion page:
DocumentCreator::create_notion_markdown(src/domain/create.rs) with aNotionMarkdown(src/domain/notion_markdown.rs); lexical-service converts it throughMarkdownInitializationPort::initialize_existing_notionand returns the Macro markdown that mention tracking reads. - Create a document with its source's dates (an import): set
NewDocumentMetadata::builder(..).created_at(..).updated_at(..). Its folder and every folder above it then widen to those dates (extend_project_dates) instead of being marked updated now. - Change content storage/markdown lifecycle:
src/domain/content.rs→src/outbound/s3_markdown_source.rs/src/outbound/markdown_init.rs→src/bin/backfill_markdown_content_location.rsif existing documents need migrating (run viajust backfill_markdown_content_location_devfrom this crate'sjustfile).
Checks
cargo test -p documents --all-features(SQLX_OFFLINEunset; needs a migrated local MacroDB foroutbound/document_create_adapterstests).just -f crates/documents/justfile checkfor an all-featurescargo check.
Gotchas
- Features compose non-trivially (
inboundpulls inaxumanddocument_create_adapters;ai_toolspulls inoutboundandports) — checkCargo.toml's[features]block before assuming a module compiles standalone. - The markdown backfill binary defaults to dry-run; the
_apply/prodjustrecipes require a typed confirmation before writing.
Related
Rules:
.agents/rules/rust/architecture.md,.agents/rules/rust/db.md· Skill:collab-surface-coreSigned document grants carry agent correlation into Sync; editor deduplication and activity debounce include the invocation ID.