Drafts (Notes)

The mobile app calls them Notes. The backend calls them Drafts. They are the same thing — a Draft document with source: 'map'.

Drafts are the central intake point for user-generated content. They capture text, attachments, voice recordings, and GPS coordinates, then feed them through an AI parsing pipeline to produce structured records (ParseResults).

Data Model

Status Lifecycle

• active — draft is being created or edited
• processing — async queue is analyzing attachments + running AI extraction
• stored — finalized, searchable, visible on the map
• discarded — soft-deleted by user
• error — processing pipeline failed

Sources

Drafts can originate from four different entry points:

Source	Entry Point	Typical Content
map	POST /drafts/from-map-note	Title + body + location + photos from the map UI
chat	POST /drafts/conversation/:id	Accumulated chat messages + attachments
vapi	Inbound phone call pipeline	Audio transcription from voice calls
manual	Direct API call	User-entered text, file uploads

Map Note Flow (Mobile)

This is the most common path for mobile users creating notes on the map.

What happens inside createFromMapNote()

1. Geospatial field lookup — queries the Field collection with $geoIntersects on the provided GPS coordinates to find which agricultural field the note falls within
2. Attachment resolution — fetches full Attachment documents from MongoDB by the provided IDs
3. Location metadata — builds a DraftLocationPoint with the matched fieldId, fieldName, note title, timestamp, and attachment references
4. Draft creation — calls initDraft() with status: 'processing' and source: 'map'
5. Async processing — enqueues the draft to the chat.attachments.analyze BullMQ queue for attachment analysis and AI parsing

GPS Detection

When messages are added to a draft, the service runs GPT-4o-mini to extract explicit GPS coordinates from the text. This only recognizes literal coordinate values — it does NOT geocode addresses or place names.

Recognized formats:

• 49.9728, -98.2804
• lat: 40.71 lon: -74.00
• 40.7128° N, 74.0060° W

GPS is also extracted from photo EXIF metadata when attachments are added.

All detected locations are stored in metadata.locations as GeoJSON Points.

AI Parsing Pipeline

The core of draft processing is DraftParseUtil.regenerateParseResults(), which assembles content from multiple sources and sends it to the LLM:

Content assembly:
┌──────────────┐
│ messages[]   │──→ message.text lines
├──────────────┤
│ transcript   │──→ full text content
├──────────────┤
│ locations    │──→ "Location 1: lat, lng ±accuracy @timestamp"
├──────────────┤
│ attachments  │──→ "[ID: xxx] (image): photo.jpg\n<analyzed content>"
└──────────────┘
        │
        ▼
  ParseProcessService.parseTranscript()
        │
        ├── TranscriptPreprocessingService (clean/normalize)
        ├── IntentDetectionService (LLM classification)
        ├── ParseService.parse() (LLM structured extraction)
        ├── WorkspaceValidationService (validate fields)
        ├── ReferenceResolutionService (resolve field/workspace refs)
        └── ReferenceValidationService (confirm refs exist)
        │
        ▼
  ParseResults saved to DB
  Draft updated with parseResultIds

After parsing, the service also:

• Injects callLogIds from the draft into parse results
• Injects fieldId from location metadata (if the workspace schema has a field reference column)
• Maps generic attachment placeholders to real attachment IDs

Controller Endpoints

CRUD

Method	Endpoint	Purpose
GET	/drafts	Get user's drafts (filter by status query param)
GET	/drafts/company/:companyId	Get company drafts (optional date range)
GET	/drafts/:draftId	Get draft by ID
POST	/drafts/from-map-note	Create note from map (with location)
POST	/drafts/conversation/:conversationId	Create blank draft for chat
DELETE	/drafts/:draftId	Soft delete (mark as discarded)
DELETE	/drafts/:draftId/permanent	Hard delete + cascade to ParseResults

Processing & Updates

Method	Endpoint	Purpose
PUT	/drafts/:draftId/metadata	Update locations, tags
PUT	/drafts/:draftId/transcript	Update transcript, re-parse, refresh summary
PUT	/drafts/:draftId/parse-results	Update parsed data directly
POST	/drafts/:draftId/store	Finalize draft (status → stored)

Sub-resources

Method	Endpoint	Purpose
GET	/drafts/conversation/:id/active	Get active draft for a chat conversation
GET	/drafts/conversation/:id/summary	Get draft summary + message count
DELETE	/drafts/:id/attachments/:attachmentId	Remove attachment from draft
DELETE	/drafts/:id/call-logs/:callLogId	Remove audio reference from draft

Key Files

File	Purpose
src/drafts/schemas/draft.schema.ts	Mongoose model definition
src/drafts/dto/draft.dto.ts	Zod validation schemas
src/drafts/drafts.controller.ts	REST endpoints
src/drafts/draft.service.ts	Business logic (main service)
src/drafts/utils/draft-parse.util.ts	Content assembly + LLM parsing integration
src/drafts/utils/draft-attachment.util.ts	Attachment extraction + ID mapping
src/drafts/utils/draft-metadata.util.ts	Location metadata helpers

Related

• Notes & Audio Upload — the upload architecture (attachment + audio pipelines)
• Module Relationships — how Drafts connect to Conversations, Fields, Attachments, etc.
• Queues & Processing — the async pipeline details