03 - Domain Model

CivicLoop by Ta-Tech Solutions Purpose: Define every entity in the system, how they relate, and the lifecycle a service request moves through. This is the contract the database, the API, and every screen are built against.

1. The core idea

CivicLoop has one central object: the Service Request. Everything else either describes it, routes it, works it, or communicates about it. If you understand the Service Request and its lifecycle, you understand the system.

A Service Request is a living record. It is created once, by a resident or an agent, and from that moment it carries its own status, its own owner, its own clock, its own history, and its own conversation - visible to the resident, the assigned agent, and County leadership at the same time. It is the opposite of the "black hole."

2. Entity catalogue

2.1 Tenancy & geography

2.2 The request and its shape

2.3 People

(The full role and permission model is Document 04.)

2.4 Routing, SLA & AI

2.5 Communication

2.6 Oversight

2.7 Visits, channels, surveys, forecasts (the 2026-05-18 wave)

These five tables landed in web/sql/civicpulse-schema.sql as part of the post-core build wave. Each has row-level security on county_id and each ships with INSERT/DELETE smoke tests in the schema dump (TaTech "trigger smoke test rule").

3. How the entities relate

County
 |-- Department          (many)
 |-- Service Area        (many)
 |-- Service Category    (many, 2-level tree)
 |-- Staff               (many)
 |-- Resident            (many)
 |-- Routing Rule        (many)
 |-- SLA Policy          (many)
 |-- Notification Template (many)
 |
 +-- Service Request     (many)  <-- the center of everything
      |-- belongs to one Service Category
      |-- routed to one Department
      |-- has one Location -> one Service Area
      |-- filed by / about one Resident
      |-- assigned to one Staff (agent)
      |-- has many Request Attachments
      |-- has many Request Events      (the timeline)
      |-- has many Request Comments    (the conversation)
      |-- has many AI Decisions        (every AI action, auditable)
      |-- has many Notifications       (every message to the resident)
      |-- may reference another Request as duplicate_of

Every box above is tenant-scoped to a County. A second county added to CivicLoop gets its own departments, categories, rules, staff, and requests, fully isolated - the multi-tenant property inherited from the Ta-Tech engine (Document 05).

The 2.7 wave plugs in cleanly:

Service Request   ----  Scheduled Visit       (0..n; ICS + alarm + SMS/email)
                  ----  Request Survey        (0..1; one per RESOLVED transition)

Department        ----  Channel               (1; the dept's slack-style room)
County            ----  Channel               (1 county-wide: #311-all)
Channel           ----  Channel Message       (0..n; including @loop replies)
Channel Message   ----> Service Request       (0..n; auto-parsed CP-... refs)

(Category, Service Area)  ----  Predicted Issue   (0..n; one per forecast run)

Triggers worth knowing about:

• requests_after_update_to_resolved writes the request_surveys row (one survey per RESOLVED transition; never duplicates if the status flips back and forth).
• scheduled_visits_after_insert writes a Request Event with the actor of the agent who scheduled it; the notifications fire from the visit lib (web/src/lib/visits/*) on the same transaction.
• All four new tables have INSERT + DELETE smoke tests in the schema dump so a broken trigger fails the SQL apply (TaTech "trigger smoke test" rule) and never reaches prod.

4. The lifecycle of a Service Request

This is the state machine. Every transition writes a Request Event and may fire a Notification.

            +-------------+
            |   DRAFT     |   resident is still composing (intake AI
            +-----+-------+   conversation in progress); not yet visible
                  |          to staff
                  v
            +-------------+
            |  SUBMITTED  |   resident confirmed; request_number issued;
            +-----+-------+   AI classifies + routes; resident gets
                  |          "received" notification
                  v
            +-------------+
            |  TRIAGED    |   routed to a Department with a priority and
            +-----+-------+   an SLA clock; AI duplicate-check run; if a
                  |          duplicate, link + merge, notify resident
                  v
            +-------------+
            |  ASSIGNED   |   a specific agent owns it; resident gets
            +-----+-------+   "a crew/agent is assigned" notification
                  |
                  v
            +-------------+
            | IN PROGRESS |   agent is actively working it; progress
            +-----+-------+   updates + photos may be added; SLA-breach
                  |          prediction runs continuously
                  |
       +----------+----------+
       v                     v
+-------------+        +-------------+
|  RESOLVED   |        | NEEDS INFO  |  agent needs something from the
+-----+-------+        +-----+-------+  resident; clock pauses; resident
      |                     |          notified with a question
      |                     +----------> back to IN PROGRESS on reply
      v
+-------------+
|   CLOSED    |   resolution confirmed; proof-of-resolution attachment
+-----+-------+   required; resident gets "resolved" notification with
      |          before/after; resident may reopen within a window
      v
+-------------+
|  REOPENED   |   resident says it is not actually fixed; returns to
+-------------+   IN PROGRESS, flagged, supervisor notified

Side states reachable from most points:

• DUPLICATE - merged into a parent request; the resident still gets that parent's updates.
• ESCALATED - sentiment or safety detection, or an SLA breach, raised it to a supervisor; not a separate status but a flag plus a supervisor assignment.
• REJECTED / NOT ACTIONABLE - out of County scope (e.g. a state highway), with a clear explanation sent to the resident and, where possible, a redirect to the right authority.

5. Rules the model enforces

These are invariants - the system guarantees them, so no screen or workflow can violate them.

1. No black holes. A request cannot move to CLOSED without a resolution note and at least one resolution-stage attachment (proof). The state machine blocks it.
2. Every transition is notified. SUBMITTED, ASSIGNED, IN PROGRESS, NEEDS INFO, RESOLVED, REOPENED each fire a Notification to the resident in their language on their channel - automatically, with no staff action required.
3. Every AI action is recorded. Classify, route, predict, detect - each writes an AI Decision row with its rationale and confidence. The AI is auditable, never a black box.
4. The clock is honest. SLA timers run against the department's real business calendar and pause in NEEDS INFO. Predicted breaches are surfaced before the deadline, not after.
5. A request can be filed without an account. A phone number is enough. Accounts are an optional convenience, never a barrier (closes the documented "mandatory account" failure mode).
6. Tenant isolation is absolute. Every row is County-scoped; no query crosses the tenant boundary.

6. What this model deliberately leaves for later

To keep v1 focused and demo-ready for May 23, the model does not yet include (but is structured to accept in Phase 2):

• Household / case linkage - connecting multiple requests and multiple residents into a household or a vulnerable-resident case. This is the seam where the Health & Human Services phase plugs in (Document 01, Section 9). The Resident and Service Request entities are designed so a future Case entity can group them without a schema rewrite.
• Work-order detail - crew scheduling, materials, labor cost. v1 treats the agent console as the work surface; deeper field-ops modeling is a later module.
• Asset registry - linking requests to specific County assets (this exact streetlight, this road segment). The Location entity is structured to later attach an asset_id.

The discipline: model the v1 loop completely and correctly, leave clean seams for Phase 2, build nothing speculative.

Next: 04 - User Roles & Permissions.