Apex Climate Solutions — Project charter

1. Objective and problem

The build gives Apex Climate Solutions one system that triages incoming requests, answers technicians' field questions with the source cited, and flags operational problems before they cost a job. Apex Climate Solutions is a simulated company: a regional HVAC (heating, ventilation and air conditioning) business with three service zones, six technicians and six vans.

HVAC was chosen over dental, property management and veterinary because it is the only one of the four where all three components have a real reason to exist. The zones differ on purpose (suburban heat pumps; commercial high-rises with strict permits; rural homes on propane, or LP gas, with long travel times), so that routing, permits and stock each matter.

Because every message is read by hand, a no-heat emergency can sit behind a routine maintenance request.

Why this and not off-the-shelf software

This system works on the step before a job is booked: it decides what an ambiguous incoming signal means and what should happen next.

The companion pricing report compares its cost with the three vendors an HVAC shop would consider:

• Jobber and Housecall Pro are the mid-tier options.
• ServiceTitan publishes no prices; unverified third-party estimates (read Oct 25, 2026) put it at $245 to $500 per technician per month plus $5,000 to $50,000 setup.

What Apex itself offers is graded urgency across channels; cited answers for technicians; permit and stock watching; and a review drafter that writes a reply to each review entered by hand, with a person approving every draft before anything is posted (Yelp replies are posted by hand). Apex is not a full field-service system. At the same call volume, Apex on Jobber's entry tier, keeping Jobber's review add-on for review requests, comes to $307 to $369 a month (estimate), against $332 to $384 at list price for Jobber's own AI phone and review route (read Oct 25–26, 2026). The case for Apex is the features it adds, not price.

2. Project scope

The build delivers a working, reviewable system for one simulated client, not a product. Each in-scope item can be checked against the built Make.com workflows (called scenarios in Make). No page, video or interview answer may claim an out-of-scope item.

In scope

• Every message, completed call and form that passes the signature check gets a database record before any judgment is made. Most failures take a safe default or reach a person through Slack or email; the few that don't are named as accepted limits in section 7.
• Urgency is rated 1 to 5 and stays with the request across channels. It has a hard floor: a cheaper model is never allowed to rate a Level 5 (an emergency) lower. Catching every true emergency (Level 5 recall) is the one number that must not slip.
• Technicians get only answers that cite a source. An answer that cites nothing the search returned is blocked.
• Messages to customers use fixed templates (the WhatsApp acknowledgement and the form confirmation email), and a person approves every review reply. The one exception is the hosted phone agent's live conversation, which follows a set script to gather the caller's details.
• Usage is held to a stated ceiling of 10,000 Make operations (Make's billing unit) a month and measured: the first measured month ran 16% over, and fixes are projected, not yet measured, to bring it to 82%.
• The design stands alone and can move between AI model providers. Where it is locked in, the lock-in is named and priced.

Out of scope

• A real client, real customer data, or a live deployment. All data is visibly synthetic.
• A fourth component, or extra tools added to look busier in place of judgment.
• A link to a job-management system such as Jobber. An overlay design exists, but its blueprint was never imported or tested.
• Any search database other than Postgres with pgvector (an extension that searches text by meaning); any AI agent nested more than one level deep.
• Automatic detection that a source manual changed outside the system.
• A queue that holds failed sends for automatic replay (a dead-letter queue). A send that fails for good raises an alert (the confirmation email also writes an audit row); a person resends it by hand.
• Fixes for the accepted demo limits: a parts report sent twice can deduct stock twice; the review post from the pre-filter cannot retry, because it runs inside a workflow that another workflow calls; the failure-test setup sends a real confirmation email; and the audit login's insert-only limit is enforced by database triggers rather than by the login's permissions.

3. Roles and stakeholders

Five roles use the system, and every action that can't be undone belongs to a person rather than a model. In this document, names beginning with # are Slack channels.

The system itself holds no approval right. It classifies, drafts, posts and reminds; a person schedules, assigns, publishes and closes.

4. The system at a glance

Every input passes through one of three fixed pipelines and leaves as a Slack post, and all three pipelines share the same data stores in Neon, a hosted Postgres database.

Deterministic pipelines with bounded AI calls, all on one record store

• Fixed rule
• Slack or input
• Store

Requests, documents and scheduled checks enter on the left and leave as Slack posts on the right. Every alert lands in one Slack channel, #system-health, in one fixed format.

5. Architecture and stack

The system runs on Make.com, keeps every data store in Neon, and puts every human touchpoint in Slack. Make.com is a visual automation platform, used here on its Core plan (10,000 operations a month). From here on, the three components are called C1 (intake and triage), C2 (technician answers from the knowledge base) and C3 (the operations watchdog and review monitor).

The design follows one rule: AI where judgment is needed, fixed rules everywhere else. Each AI call does one job, returns a fixed format, and is checked before anything uses it. Everything around those calls is fixed rules (filters, routers, database functions and scheduled checks), and a person decides every dispatch, stock change and public reply. The hosted phone agent follows a set script to gather a caller's details.

Make's workflow-to-workflow call passes typed inputs, needs no public web address and uses 0 operations. A webhook is a web address that receives incoming messages. Embeddings are the numeric fingerprints used to search documents by meaning, and each AI step runs on the model that fits its use. Directus, an admin screen generated from the database, sits on the CRM.

Component 1: intake and triage (C1)

Every request that reaches the pipeline gets a database record before any judgment is made, then runs through fixed steps in order: a duplicate check on the channel's own event ID; a pre-filter (sender present, length in bounds, not blocklisted, fewer than 12 messages per 2 minutes per sender); an exact-match customer lookup; equipment matching by approximate text search inside the database; a voice safety rule (a reported gas or burning smell forces Level 5); a format check on the AI replies; then routing.

Each intake makes at most three AI calls, two for a known customer: a junk gate, an extraction of name and equipment details, and an urgency rater that returns a whole number from 1 to 5 against a written scoring guide. The rater scored 66 of 66 on its development test set.

A Level 5 posts to #urgent, tagged Uncorroborated when nothing beyond the message text backs it; Levels 1 to 4 post to #normal-triage with a triage window. If an AI reply fails the format check or the database fails, no job is created and the raw request goes to #urgent for a person, so that failure is never silent.

Component 2: technician answers (C2)

Three simulated documents written to look like real vendor material (a diagnostic guide, a permit code covering the three zones, and a warranty policy) are loaded by posting a PDF in a private Slack channel. The loader refuses pages with too little text and documents with a future effective date. It splits each file into 1,800-character passages tagged with their section, converts each file to searchable vectors in one call, and switches to the new version in a single database transaction, so the old version stays live if loading fails.

A technician asks in #tech-help. A fixed nine-phrase rule, not AI, sends stock questions to C3 and everything else to the answer step. The answer comes back as JSON in a fixed structure and must cite passages the search actually returned; the source list is built from database rows, never written by the model, and an answer that cites nothing is blocked. The minimum match score for a passage to count was set at 0.72 on a 16-case test set.

Component 3: operations watchdog and review monitor (C3)

One database function returns every neglected job with its reason: unassigned for 45 minutes; no technician update for 4 hours; permit pending for 72 hours; truck at or below minimum stock; no job thread after 5 minutes; or assigned with no notice after 10 minutes. It replaced a loop of Make modules (iterator, router and aggregator) that would have cost about 57,000 operations a month.

The watchdog runs every 30 minutes from 7 a.m. to 8 p.m. Panama City time (UTC−5), with reminder-only runs overnight. It calls a model to rank the list only when two or more jobs are flagged, and every flagged job reaches the digest whatever the model returns.

Technicians report parts used in the job thread. An AI step reads the parts back, and the technician confirms, discards or undoes by reaction (✅ confirm, ❌ discard, ↩️ undo). A drafter writes a reply to each review entered by hand, and a person must approve every draft before anything is posted; Yelp replies are posted by hand. Pulling and posting Google and Instagram reviews is designed, not built (section 9). The approval step claims the draft before acting, which prevents double publishing, and nothing is ever published automatically.

Cross-cutting rules

• Most replies to technicians and approvers retry three times, 15 minutes apart, using Make's built-in retry (called Break); if the retries run out, nobody is told. That retry cannot run in a workflow that another workflow calls, so when the two intake dispatch posts fail they send an email and a #system-health alert instead, which testing confirmed. The missed-call notice, the daily digest of messages set aside as probably not service requests, and the form heartbeat alert (the form script checks in daily) do the same instead of retrying. Alerts are never retried except the form heartbeat watcher's, and writes are never retried except the parts confirm, undo and discard.
• In the knowledge base and the watchdog, AI calls and reads get one quick retry. If that fails and someone is waiting, they get an apology and an alert is raised; if nobody is waiting, only the alert. The three intake AI calls make one attempt, then fall back to a safe default: the message is treated as real, an unmatched field is left unmatched, or an alert is raised.
• The audit log accepts new rows only, enforced by a database trigger; senders are stored hashed and no raw message text is kept. Intake writes a row at each main step; the knowledge base writes one when an answer is blocked, and the watchdog writes rows for review outcomes and stock discards.
• Each workflow runs under its own database login with only the permissions it needs (least privilege). No Make or Directus login can delete or empty a business table; jobs are created through a database function that runs with its owner's rights.
• Operations budget: 84% of plan (estimate), 116% in the first full demo month (measured), and 82% after the fixes (projected). The gap came from unwanted traffic reaching paid steps before a filter stopped it.

Alternatives considered

• Automation platform. n8n self-hosts cheaply but adds a server to run and secure; its per-execution pricing was noted as the main portability argument and kept as a design note only.
• Database host. Three separate databases (document library, audit log, CRM) keep customer data apart from the knowledge base by structure rather than by convention. Neon's free tier allows more projects and suited the demo's volume. Keeping vector search inside Postgres (pgvector) instead of adding a separate vector database also lets all three share one set of access roles. The move from Supabase to Neon changed only the host; the architecture stayed the same.
• CRM admin interface. A Make data store holds no relations and no permissions.
• Intake orchestration. An AI agent that plans its own steps was considered and set aside. Fixed steps make every audit row a plain write and remove the risk of unbounded cost.
• Model providers. Embeddings and answers drawn from the documents held up on Google's free tier, and the documents are simulated, so splitting providers cut cost without changing outcomes.
• Voice. Any of the three could fill the slot. WhatsApp calling stayed a design note.
• Notifications. Slack reactions and threads work as lightweight approvals. SMS would add a paid vendor, a second channel to monitor and no thread history.

6. Design principles

The hardest part of the build was deciding what not to automate, and six rules guided those decisions.

1. Use an AI agent only where a step has a real loop. An AI agent (a model that plans its own steps) earns its place only when a step must search, get zero, one or many results, and try again. Intake has no such loop: an unknown sender has no records, a known customer with one unit has one row, and a customer with several units needs a person or the customer to decide. The same test on the review monitor found no loop either, so C1 has three single AI calls with fixed reply formats, C3 has four, and the risk of open-ended cost against the operations ceiling cannot occur.
2. Fixed rules move the data, and a model is called only where the input is ambiguous. Filters, routers, database functions and fixed phrase rules do the moving. The model answers questions such as: is this junk, what equipment is named, how urgent is it, what does this review say. Every model call returns plain JSON in a fixed structure, and a cleanup step strips any code formatting the model adds.
3. Choose each model by the cost of a wrong answer. Only a wrong urgency rating can't be undone, so the rater runs on the strongest model. A cheaper model matched on 43 of 43 cases, then missed six Level 5s on a later prompt version, so the switch was reversed. The junk filter runs on the cheapest model that passed its test set; extraction, which had no formal test, runs on a small, low-cost model.
4. A customer's identity comes from the channel, never from what the message claims. Customer lookup is an exact match on the channel's own ID. Approximate matches appear on the triage card as suggestions and are never applied. A public reviewer's name is never matched to a customer record.
5. Limit what each step can see instead of relying on the prompt. A field the model never receives cannot leak, so lookup functions return only what the step needs. Telling the model "do not reveal addresses" is a request it can ignore; not giving it the address is a limit it cannot break. The boundaries on what a model can reveal are set by what data a step receives.
6. Every failure path is spelled out. In Make, a router's branches do not rejoin and a malformed value matches no branch, so the format check sits before routing. Every send has a chosen retry or alert behavior, and the one unacceptable outcome, a lost request, has its own route to #urgent. The few paths that still end without a post are named as accepted limits in section 7.

Two working rules shaped the record as much as the system. The first is independent scoring: two of the three formal AI tests were first scored in the session that tuned them; all three were re-scored in a separate session before any result was published. The second is that every capability claim about the project is checked against the demo-versus-live table (section 9) before it is used.

7. Success criteria and evaluation

Each success criterion was set as a number before the thing it measures was tested. The project counts as done well when every criterion below holds. Three rules governed the testing. Each of the three tests had its pass rules written before its first scored run. Two of the three formal AI tests were first scored in the session that tuned them; all three were re-scored in a separate session before any result was published. A pass applies only to the version that was scored, so a prompt or model change triggers a re-run.

The fixes from the production sweep were tested independently on test copies, except the paths listed below as built but unproven.

Exceptions to "no inbound request is lost." Critical paths (a customer request reaches a person, an emergency reaches dispatch) have guards, alerts and backups. Rare, low-impact cases are accepted and recorded. The accepted limits and what each costs:

• A reminder whose count fails to save repeats on the next run: over-alerting, not loss.
• The daily heartbeat check's alert cannot name the missing entries.
• A heartbeat check-in from the wrong source gets "OK" and is caught only by the daily check, up to about 26 hours later.
• If the step that answers the form script fails, the script is not told the outcome.
• An incomplete Google Form response raises an alert that cannot identify the customer. Every question is required, so this happens only if the form or its script is edited.
• One Slack connection carries every alert. Email backs up the dispatch posts, the digest, the heartbeat, the missed-call notice and the message-flood alert, but not the rest.
• Nothing watches the monitors themselves; a real deployment would add an outside uptime check.
• Unused routing for a retired grace period stays in the dispatch step; no job can reach it.
• A technician or approver reply whose retries (3, 15 minutes apart) run out tells nobody, and stock can be deducted while the "saved" reply fails, which leaves the technician no message to undo from.
• Rare silent drops: an uploaded document with no file type, a negative stock quantity and an unknown action in the job-thread step.
• If Slack is down at 8 a.m., that day's digest of messages set aside as probably not service requests is skipped, with an email and an alert, and its items return the next day: one late day.
• A #tech-help photo post is answered from its text, with a note that the photo was not read. That note fires for any shared file, can be missing on odd uploads and is not alerted if it fails: an odd or missing note, rarely.
• If a photo post's hand-off to the answerer fails, the photo note mentions an answer that does not exist: a confusing extra line.
• Some alerts show a double space after "What failed:": looks only.
• Paths closed without an independent test: parts confirm and undo; the document loader's refusal replies, split-failure alert and forced AI retry; the assignment notice with no secret header, two simultaneous edits or a cleared technician. These rare paths are built but unproven.
• Three fixed failure paths were never forced to fail in testing: the low-attention digest failing to post one of its items; the phone-call branch of the intake alert for a failed signature step; a form heartbeat checker alert while Slack is down. They are rare, off the normal path and low impact, so each is built but unproven on that one path.
• If a job's Slack thread is deleted, nothing re-creates it: the watchdog step that would do so was never built.

Behavior by design:

• A request that fails the signature check is refused with an alert and answered "OK", so it is not resent: an attacker must not trigger retries.
• If the junk gate fails, the message carries on as real, with the audit row as the trace: a lost real request costs more than junk reaching a person.
• A stock reaction from anyone but the reporting technician changes nothing and gets a refusal reply; only if that reply fails is nothing said.
• New intake alerts fire before the signature check, so while the secrets store is failing, unchecked text can reach #urgent: a noisy alert is preferred to a silent failure.
• Unlisted reactions or outcomes in operations are ignored.
• From a sender's 12th message within 2 minutes, one #urgent alert names the sender; their later messages in that window are dropped without another alert.

8. Security, data ownership and platform policy

The only public entry points are five authenticated Make webhooks. They receive phone and form intake, WhatsApp intake, the job-assignment notice from Directus, the document loader's uploads, and the Google Form script's daily check-in. Slack events for the other staff channels arrive through Make's own Slack connection, not through a web address this build exposes.

A test copy gets a webhook of its own only while it is under test, and that webhook is removed after verification. No public endpoint is added without a charter entry saying why. A live security check found Neon's Data API (web access to the database) exposed, contradicting an earlier decision; it was deleted without ever being called.

Security position

• Credentials are never kept in workflow fields, prompts, Jira, the charter or Miro; webhook secrets do appear in Make's private run history, an accepted limit. A credential that appears in any chat or tool result is replaced the same day.
• Inbound webhook checks: a cryptographic signature check (HMAC) proves each Retell, WhatsApp and Slack document-loader request came from the real sender, with a 5-minute age limit on Retell and Slack. The Google Form, its daily check-in and the Directus job-edit hook carry a secret header instead. A refused request posts one alert and gets a success reply (HTTP 200) so the sender does not retry; the accepted cost is that a wrongly refused message must be replayed by hand. If a secret is missing or empty, every request is refused. Forged-request tests verified the checks and found one defect (an empty message body crashed the check), fixed the same day. The document loader's check was added later in the build; it refused forged, unsigned and replayed requests and let a real upload through.
• Least privilege: each workflow has its own database login, none can delete or empty a business table, Directus users see only the columns they are granted, and jobs are created through a function that runs with its owner's rights.
• Personal data: the document library holds no customer data (checked and found empty). Customer details live only in the CRM (mock rows flagged), the audit log and Slack. The audit log never stores raw message text: senders are hashed, emails are redacted, and the only text drawn from a customer's message is a short symptom label.
• Controls adopted from the OWASP Top 10 for large language model applications, a standard security checklist: a dated list of vendors for each step; documents enter only through a private admin channel, with a content fingerprint (hash) and the embedding model recorded for each load; every prompt is treated as public; and no public path leads to the document search store.
• Anything leaving the project (blueprint export, screenshot, board export) is cleaned of webhook addresses, connection IDs, org and project IDs.

Data ownership and permanence

• The project owner holds every store through accounts the project controls; nothing depends on Make's run history, which it keeps for 30 days. Every store exports as a Postgres dump or blueprint.
• The audit log accepts new rows only, enforced by database triggers; tests as the Make login confirmed it cannot disable or bypass them. The account holder still can, so the log is protected against changed history but is not tamper-proof. A production system would add a copy that cannot be altered for a set period (retention-locked), or a daily export to an account the owner does not administer.
• Customer records are never erased. A customer who leaves is marked declined and kept, so their job history stays intact, and the database itself refuses to delete any customer that has jobs attached. No Make or Directus login has permission to delete in the first place.
• Switching providers: each AI step is a plain web request (HTTP call), then a cleanup step that strips code formatting, then a check against a fixed JSON structure, so a provider swap does not touch later steps. The model name and prompt are set inside each Make module rather than read from a settings table.

Third-party platform policy

Risks and mitigations

9. Demo mode versus a live deployment

This table is the reference for every capability claim about the project. Apex demonstrates an architecture and is not a running service: traffic is synthetic, and nothing is deployed for a real company. Built means it exists and ran; Designed means it is drawn and documented but not built; Declined means it is out of scope on purpose.

10. Timeline and status

The project ran as a phased, largely sequential delivery (waterfall): discovery, then design, then build, then test. Design decisions kept arriving while build and test were under way, which is why those three bars overlap. The build is complete and its main paths are tested; a few rare paths are built but unproven, listed as accepted limits. The portfolio-site, demo and closeout phase has a target finish of November 15. After the initial launch, add-ons and improvements would move to short iterative cycles (agile, Scrum).

Design, build and test ran in parallel; site, demo and closeout are under way

Phases by date, 2026. Bars show first and last recorded activity per phase; the current phase runs to the target.

• First to last recorded activity
• Wrap-up target

The work was tracked as 139 backlog items, and 110 are done. Closed items include 20 design, 22 build and 14 evaluation and test items; 11 demo and closeout items are in progress. The first charter entry is dated August 20, 2026; the first Make workflow was built in the week of September 14; the first independent test passed on September 27.

11. Decision log

The project owner made every decision in this log; it lists the ones that shaped the architecture, newest first, with the reasoning at the time. Recording the reasoning lets a later reader tell a decision from an assumption. A superseded entry stays in the log with its replacement named. The full record of about 150 dated decisions is kept in the project's working notes; this table carries the ones a reviewer needs to understand the system.

12. Companion documents

The charter holds intent and decisions; three other records hold everything else. Each kind of information has one home, so the records do not drift apart.

Supporting documents: the pricing report (a cost comparison of Jobber, Housecall Pro, ServiceTitan and Apex's own running cost of about $59 to $121 a month, an estimate).