How it works
MATTER
Construction project platform. Runs about 180 active projects and $14M in contracts at Delta Construction: chat, RFIs, submittals and bids in one place, showing who owes the next move.
Live · runs Delta ConstructionVisit the site ↗
Architecture
Hover a box to trace its connections; click it for what it does.
- request
- webhook, queue, schedule
- the heart
- outside service
AClients· 4Web app · Respond by link · Missive sidebar · Claude & MCP clients
Web appNext.js 15 · React 19UI
UI · Next.js 15 · React 19
The app people use on site and in the office, built mobile-first for phones and iPads with gloves on. Its types are generated from the Java DTOs, so the front end and back end can’t drift.
Talks to
- → Public API (HTTPS · JWT)
- → Live sockets (live)
Respond by linkRFI · submittal · bid · exhibitUI
UI · RFI · submittal · bid · exhibit
Pages outside the app that architects, engineers, subs and clients open from an emailed link or a short typed code: answer an RFI, review a submittal, submit a bid, approve a drawing exhibit, join a contractor’s network. No account needed.
Talks to
- → Public API (token)
Missive sidebarCRM in the inboxUI
UI · CRM in the inbox
A panel inside the shared inbox: it recognises the contact on an email, logs the interaction, and sets a follow-up without leaving the conversation.
Talks to
- → Public API
Claude & MCP clientssigned in as a userEXTERNAL
EXTERNAL · signed in as a user
Claude Desktop or any MCP client, signed in as a real person through OAuth. It gets exactly what that person could do in the app.
Talks to
- → MCP endpoint (MCP)
- → OAuth server (OAuth)
BGateway· 3Public API · Live sockets · MCP endpoint
Public APISpring Boot · JWT · keysSERVICE
SERVICE · Spring Boot · JWT · keys
The only door in. It checks the JWT or an integration API key, resolves the user, company and tenant once, throttles the endpoints that could be abused, and forwards each request to the platform with signed identity headers.
Talks to
- ← Web app (HTTPS · JWT)
- ← Respond by link (token)
- ← Missive sidebar
- → AI service (proxy)
- → Projects (REST)
Live socketsWebSocketsREALTIME
REALTIME · WebSockets
Held by the gateway: chat, notifications, who is on which drawing, which conversation each tab is reading, and the notice that a new version of the app is out.
Talks to
- ← Web app (live)
- ← Redis 7 (pub/sub)
MCP endpointJSON-RPCAI
AI · JSON-RPC
The MCP transport. Claude’s tool calls arrive here and run as the signed-in user.
Talks to
- ← Claude & MCP clients (MCP)
- → Tool registry (as the user)
CAI & MCP· 6Catalogue ingestion · AI service · Agents · Workflows · Tool registry · OAuth server
Catalogue ingestionfrom past documentsAI
AI · from past documents
Reads a company’s past project documents and proposes budget and qualification catalogue entries. Nothing lands until a person with the right permission accepts it.
Talks to
- → Catalogues
AI serviceNode · FastifyAI
AI · Node · Fastify
Runs the assistant’s and the agents’ turns: streams the model, offers the tool list, applies each company’s model policy and evaluates hooks once per turn. It also transcribes voice notes and drafts meeting minutes.
Talks to
- ← Public API (proxy)
- → Tool registry (list · call)
- ← Agents
- → Claude · OpenRouter (stream)
- → Daily logs
Agentscommands · skills · hooksAI
AI · commands · skills · hooks
Each company’s named AI agents: built-in construction commands, their own skills, hooks with an audit trail, and delegation to one other agent at most.
Talks to
- → AI service
Workflowstriggers · schedulesJOB
JOB · triggers · schedules
Workflow definitions wired step to step, each output checked against the next input, run on a trigger or a schedule as the person who owns them.
Tool registry234 tools · 24 domainsAI
AI · 234 tools · 24 domains
Every action an AI may take, declared on the platform’s own service methods, with a schema derived from the DTO and the caller’s permissions checked on every call. Read, write and workflow tools are marked apart, so clients know which ones change things.
Talks to
- ← MCP endpoint (as the user)
- ← AI service (list · call)
- → Projects (every domain)
OAuth serverOAuth 2.1SERVICE
SERVICE · OAuth 2.1
Lets MCP clients sign in as a person. Redirect addresses are checked strictly so the consent step can’t be abused.
Talks to
- ← Claude & MCP clients (OAuth)
DPrecon· 7Leads & CRM · Estimating schedule · Scope & estimate · Catalogues · Bidding · Client proposals · Sub network
Leads & CRMaccounts · follow-upsSERVICE
SERVICE · accounts · follow-ups
Leads with statuses each company sets, client accounts, contacts, interactions and follow-ups, and a won/lost analysis the AI can write up on a schedule.
Talks to
- → Estimating schedule
- ← Missive (webhooks)
Estimating schedulewho · when · hoursSERVICE
SERVICE · who · when · hours
Which estimator is on which bid, on which dates, with hours planned next to hours spent.
Talks to
- ← Leads & CRM
- → Scope & estimate
Scope & estimateROM · conceptual · bidSERVICE
SERVICE · ROM · conceptual · bid
The estimate as a tree of divisions, subtrades and cost lines, taken through ROM, conceptual and formal-bid stages, with a snapshot and a diff at every revision. Drawn in full below.
Talks to
- ← Estimating schedule
- ← Catalogues
- ← Bidding (carry a bid)
- → Client proposals (priced)
Cataloguesbudget · qualificationsSERVICE
SERVICE · budget · qualifications
Each company’s standing budget items and qualifications, applied to a new scope automatically and shared across all its projects.
Talks to
- ← Catalogue ingestion
- → Scope & estimate
Biddingpackages · levelingSERVICE
SERVICE · packages · leveling
Bid packages per trade, invitations, addenda and questions, bids with a schedule of values and alternates, leveling, and the award.
Talks to
- → Scope & estimate (carry a bid)
- → Contracts & SOV (award)
Client proposalsversions · decisionSERVICE
SERVICE · versions · decision
The proposal the client sees, generated from the priced scope: versions, hand edits, an optional review, send, and the client’s decision. Accepting a version locks the scope’s prices.
Talks to
- ← Scope & estimate (priced)
- → Contracts & SOV (accepted)
Sub networkjoin links · scoresSERVICE
SERVICE · join links · scores
The subcontractors a contractor works with: they join from a link, and the contractor scores their work against weights it sets.
EDelivery· 8Projects · RFIs · Submittals · Drawings · Daily logs · Schedule · Meetings · Forms
Projectsdashboard · directorySERVICE
SERVICE · dashboard · directory
The centre of the model. Everything belongs to a project and the companies and people on it, each with a permission level per tool.
Talks to
- ← Tool registry (every domain)
- ← Public API (REST)
- ← Procore (import)
RFIsball in courtSERVICE
SERVICE · ball in court
Requests for information, one question each, with drafts, assignees, watchers and a due date set by urgency in business days. Drawn in full below.
Talks to
- → Notifications (ball moved)
Submittalsrevisions · votesSERVICE
SERVICE · revisions · votes
Submittals go round in revisions. Every assigned reviewer gives an official answer, and the most restrictive one decides the revision.
Drawingssplit · diff · markupSERVICE
SERVICE · split · diff · markup
Splits a plan set into sheets, keeps every revision, renders a diff between two, and holds markups, comments and location pins. Drawn in full below.
Talks to
- → Object storage
- ← Exhibit approvals
Daily logsdictation · approvalSERVICE
SERVICE · dictation · approval
The day on site: entries, attachments and a calendar, submitted for approval. A voice note can be turned into proposed entries for the person who spoke it to confirm.
Talks to
- ← AI service
Scheduleactivities · critical pathSERVICE
SERVICE · activities · critical path
Schedule activities with owners and dates, a Gantt view and the critical path.
Meetingsagenda · AI minutesSERVICE
SERVICE · agenda · AI minutes
Series, agendas, attendance and minutes. A pasted transcript becomes drafted minutes and action items; accepting the draft turns the actions into assigned tasks.
Formstemplates · submissionsSERVICE
SERVICE · templates · submissions
Company form templates deployed to projects and filled in on site.
FMoney· 4Change orders · Contracts & SOV · Pay applications · Budget & costs
Change ordersevents → ordersSERVICE
SERVICE · events → orders
Change events priced line by line, then change orders that are submitted, approved or rejected against a contract.
Talks to
- → Contracts & SOV
Contracts & SOVprime · subcontractsSERVICE
SERVICE · prime · subcontracts
Prime contracts and subcontracts with schedules of values. Contract sums are derived from the lines, never stored, and once a schedule of values is locked its values change only through a change order.
Talks to
- ← Client proposals (accepted)
- ← Bidding (award)
- ← Change orders
- → Pay applications
Pay applicationsAIA G702 / G703SERVICE
SERVICE · AIA G702 / G703
Applications for payment on the AIA forms, by billing period with retainage: who may create, submit, certify and pay each one, rendered to PDF.
Talks to
- ← Contracts & SOV
Budget & costscost codes · direct costsSERVICE
SERVICE · cost codes · direct costs
The project budget by cost code, and direct costs with their attachments.
GCollaboration· 4Chat · Notifications · Tasks · Calendar
Chatreal timeSERVICE
SERVICE · real time
Project, group and direct conversations with mentions and attachments. Drawn in full below.
Talks to
- → Redis 7 (publish)
Notificationsin-app · emailSERVICE
SERVICE · in-app · email
Tells the right people when something moves, in the app and by email, by each person’s own settings.
Talks to
- ← RFIs (ball moved)
- → Redis 7
- → Mail queue
- ← Scheduled jobs
Tasksboards · initiativesSERVICE
SERVICE · boards · initiatives
Tasks with statuses each team sets, watchers, comments and attachments, grouped into initiatives, on boards, a timeline and a calendar.
Calendarslots · bookingsSERVICE
SERVICE · slots · bookings
Everyone’s meetings, tasks and personal blocks in one place, with free-slot finding across people and appointment booking.
HDocuments· 6Files & folders · Documents · Photos · Exhibit approvals · 3D models · Search
Files & folderscompany · projectSERVICE
SERVICE · company · project
One library for files at company and project level, with folder templates for new projects, share lists and markups.
Talks to
- → Autodesk APS
Documentsmarkdown · branded PDFSERVICE
SERVICE · markdown · branded PDF
Documents written in the app or generated by it, with mentions, rendered to PDF on the server in each company’s own branding.
PhotosalbumsSERVICE
SERVICE · albums
Site photos in albums, with access granted per album.
Exhibit approvalssigned by linkSERVICE
SERVICE · signed by link
Sends one revision of a drawing out for approval and keeps the signed record of exactly which revision was agreed to.
Talks to
- → Drawings
3D modelsIFC · three.jsSERVICE
SERVICE · IFC · three.js
IFC building models imported to a project and viewed in the browser.
Searchnames + meaningSERVICE
SERVICE · names + meaning
One search box over the projects you can reach: a pass for names and numbers and a pass for meaning, then each item’s own access check.
IData & jobs· 5PostgreSQL 16 · Redis 7 · Object storage · Scheduled jobs · Mail queue
PostgreSQL 16Liquibase migrationsSTORE
STORE · Liquibase migrations
The system of record for every module, with versioned schema migrations.
Redis 7cache · pub/subSTORE
STORE · cache · pub/sub
Caching, plus the pub/sub channels that carry chat, notification, presence and viewing events between servers.
Talks to
- ← Chat (publish)
- ← Notifications
- → Live sockets (pub/sub)
Object storageS3-compatibleSTORE
STORE · S3-compatible
Drawing sheets, diff overlays, photos, models and documents, served through short-lived signed links.
Talks to
- ← Drawings
Scheduled jobs19 · one server eachJOB
JOB · 19 · one server each
Overdue RFIs and submittals, follow-up cadences, tasks due soon, workflow triggers, search indexing and cleanup. Each job takes a lock, so it runs on one server only.
Talks to
- → Notifications
Mail queueoutbox · retriesQUEUE
QUEUE · outbox · retries
Outgoing email is queued and sent in the background, through each company’s own mail server.
Talks to
- ← Notifications
- → Company mail (SMTP)
JOutside· 5Procore · Missive · Autodesk APS · Company mail · Claude · OpenRouter
Procoreone-way importEXTERNAL
EXTERNAL · one-way import
Projects, RFIs, submittals, drawings, documents, photos and financial history are imported from Procore over OAuth. Nothing is written back.
Talks to
- → Projects (import)
MissivewebhooksEXTERNAL
EXTERNAL · webhooks
The shared inbox. Its signed webhooks bring email activity into sales.
Talks to
- → Leads & CRM (webhooks)
Autodesk APSOAuth · filesEXTERNAL
EXTERNAL · OAuth · files
Autodesk Platform Services: linked projects, folders and files.
Talks to
- ← Files & folders
Company mailSMTP per companyEXTERNAL
EXTERNAL · SMTP per company
Each company sends from its own mail server, so email comes from them, not from MATTER.
Talks to
- ← Mail queue (SMTP)
Claude · OpenRoutermodelsEXTERNAL
EXTERNAL · models
The models behind the assistant and the agents, chosen per company within the platform’s policy, optionally on the company’s own keys.
Talks to
- ← AI service (stream)
Connections · 36
→ request · ⇢ webhook, queue or schedule
- Web app → Public API · HTTPS · JWT
- Respond by link → Public API · token
- Missive sidebar → Public API
- Web app → Live sockets · live
- Claude & MCP clients → MCP endpoint · MCP
- Claude & MCP clients → OAuth server · OAuth
- Public API → AI service · proxy
- MCP endpoint → Tool registry · as the user
- AI service → Tool registry · list · call
- Agents → AI service
- AI service → Claude · OpenRouter · stream
- Catalogue ingestion → Catalogues
- Tool registry → Projects · every domain
- Public API → Projects · REST
- Leads & CRM → Estimating schedule
- Estimating schedule → Scope & estimate
- Catalogues → Scope & estimate
- Bidding → Scope & estimate · carry a bid
- Scope & estimate → Client proposals · priced
- Client proposals → Contracts & SOV · accepted
- Bidding → Contracts & SOV · award
- Change orders → Contracts & SOV
- Contracts & SOV → Pay applications
- AI service → Daily logs
- RFIs → Notifications · ball moved
- Chat ⇢ Redis 7 · publish
- Notifications ⇢ Redis 7
- Redis 7 ⇢ Live sockets · pub/sub
- Notifications ⇢ Mail queue
- Mail queue ⇢ Company mail · SMTP
- Scheduled jobs ⇢ Notifications
- Drawings → Object storage
- Exhibit approvals → Drawings
- Files & folders → Autodesk APS
- Procore ⇢ Projects · import
- Missive ⇢ Leads & CRM · webhooks
Inside
Preconstruction is one pipeline, not five tools. A lead becomes a project with a scope, the scope is priced from catalogues and real bids, the client accepts a proposal, and the contract and its schedule of values are generated from what they accepted.
Hover a box to trace its connections; click it for what it does.
ASales· 4Leads · Follow-ups · Estimating slot · Win/loss analysis
Leadsstatuses you setSERVICE
SERVICE · statuses you set
Every opportunity, moving through statuses the company defines, tied to a client account and its contacts.
Talks to
- → Follow-ups
- → Estimating slot (scheduled)
- → Win/loss analysis (won · lost)
- → Estimate stages (becomes a project)
Follow-upscalls · emails · inboxSERVICE
SERVICE · calls · emails · inbox
Calls and emails due on a lead, logged as interactions, including the ones logged from the shared inbox.
Talks to
- ← Leads
Estimating slotestimator · dates · hoursSERVICE
SERVICE · estimator · dates · hours
The bid on the estimating schedule: which estimator, which dates, hours planned and hours spent.
Talks to
- ← Leads (scheduled)
Win/loss analysiswritten by the AIAI
AI · written by the AI
A report on why leads were won or lost, written by the model from the pipeline’s own data, on demand or on a schedule.
Talks to
- ← Leads (won · lost)
BScope· 7Estimate stages · Scope tree · Catalogues · Revisions · Bid packages · Carry a bid · Pricing
Estimate stagesROM · conceptual · bidSERVICE
SERVICE · ROM · conceptual · bid
One estimate per stage. Moving a project to ROM starts tracking its scope; conceptual and formal bid follow, and a stage can be stepped back.
Talks to
- ← Leads (becomes a project)
- → Scope tree
Scope treedivisions · subtrades · linesSERVICE
SERVICE · divisions · subtrades · lines
Divisions, subtrades and cost lines, each subtrade assignable to a company, with notes and attachments, and an audit log of every change.
Talks to
- ← Estimate stages
- ← Catalogues
- → Revisions (snapshot)
- ← Carry a bid (prices lines)
- → Pricing
Cataloguesbudget · qualificationsSERVICE
SERVICE · budget · qualifications
Standing budget items and qualifications that apply themselves to a new scope, shared by every project in the company.
Talks to
- → Scope tree
Revisionssnapshot · diffSERVICE
SERVICE · snapshot · diff
Each revision snapshots the whole scope and every stage estimate, so any two can be compared line by line.
Talks to
- ← Scope tree (snapshot)
Bid packagesinvite · level · awardSERVICE
SERVICE · invite · level · award
A trade’s scope packaged for bidding. Subs bid from a link with a schedule of values and alternates, and the bids are levelled side by side.
Talks to
- → Carry a bid
- → Subcontracts (award)
Carry a bidone transactionSERVICE
SERVICE · one transaction
Carries one bid across a subtrade at once: every line it prices takes its number, the rest keep theirs, and nothing is written if it prices none.
Talks to
- ← Bid packages
- → Scope tree (prices lines)
Pricingbasis · markup · GRSERVICE
SERVICE · basis · markup · GR
Each line’s carried cost basis, markups and general requirements. Amounts are computed on the server, never taken from the browser.
Talks to
- ← Scope tree
- → Client proposal (priced scope)
- ← Client’s decision (locks prices)
CProposal· 3Client proposal · Review & send · Client’s decision
Client proposalversions · editsSERVICE
SERVICE · versions · edits
Generated from the scope’s client view. A draft can be edited by hand and refreshed from the scope without losing those edits.
Talks to
- ← Pricing (priced scope)
- → Review & send
Review & sendoptional reviewSERVICE
SERVICE · optional review
An optional internal review, then send. Sending records the recipients and writes a revision.
Talks to
- ← Client proposal
- → Client’s decision
Client’s decisionaccepted · declinedSERVICE
SERVICE · accepted · declined
The client’s answer, recorded against the version they saw. Accepting it locks the scope’s prices.
Talks to
- ← Review & send
- → Pricing (locks prices)
- → Prime contract (accepted)
DContract· 4Subcontracts · Pay applications · Prime contract · Change orders
SubcontractsSOV from the awardSERVICE
SERVICE · SOV from the award
An awarded bid’s schedule of values, line detail and all, carried onto a payable subcontract.
Talks to
- ← Bid packages (award)
- → Pay applications
Pay applicationsG702 / G703 · retainageSERVICE
SERVICE · G702 / G703 · retainage
Billing by period on the AIA forms, with retainage, certification and payment.
Talks to
- ← Subcontracts
- ← Prime contract
Prime contractSOV from the proposalSERVICE
SERVICE · SOV from the proposal
Generated from the accepted proposal, with its schedule of values built from the scope.
Talks to
- ← Client’s decision (accepted)
- → Pay applications
- ← Change orders
Change ordersafter the SOV locksSERVICE
SERVICE · after the SOV locks
Once a schedule of values is locked, its values change only through an approved change order.
Talks to
- → Prime contract
Connections · 19
→ request · ⇢ webhook, queue or schedule
- Leads → Follow-ups
- Leads → Estimating slot · scheduled
- Leads → Win/loss analysis · won · lost
- Leads → Estimate stages · becomes a project
- Estimate stages → Scope tree
- Catalogues → Scope tree
- Scope tree → Revisions · snapshot
- Bid packages → Carry a bid
- Carry a bid → Scope tree · prices lines
- Scope tree → Pricing
- Pricing → Client proposal · priced scope
- Client proposal → Review & send
- Review & send → Client’s decision
- Client’s decision → Pricing · locks prices
- Client’s decision → Prime contract · accepted
- Bid packages → Subcontracts · award
- Subcontracts → Pay applications
- Prime contract → Pay applications
- Change orders → Prime contract
Four flows
An RFI changes hands
Walk through it and each step lights the parts it runs through in the drawings above.
By count
- actions Claude can take in it
- 234
- active projects at Delta
- ~180
- in contracts managed through it
- $14M
- things people outside do from a link, with no account
- 5
Notes
- N.1Nobody updates ball-in-court by hand. It follows the RFI: while it’s open it sits with the company that has to answer, once it’s answered it goes back to whoever asked, and closing it clears it. Only an official answer moves it.
- N.2I didn’t give the AI its own way in. Claude, the assistant and every agent use the same actions a person has, as that person, and anything that moves a record through a workflow only runs when someone asks for it.
- N.3A proposal the client accepts locks the scope’s prices, and the contract and its schedule of values are generated from it, so what was sold is what gets billed.
- N.4Presence runs on a heartbeat, not on the connection. An iPad that loses signal on site drops off the sheet by itself instead of leaving a ghost behind.
Built by
I design, architect and build software products like this one.
More systems