05 - System Architecture

CivicLoop by Ta-Tech Solutions Purpose: Describe how the system is built - the platform engine it stands on, the multi-tenant model, the technology, how it works offline, where it is hosted, and how it ships. Written so an engineer reads it as a spec and a County technical reviewer reads it as due diligence.

1. The honest framing: this is not built from scratch

CivicLoop is a new product on a proven platform engine. Ta-Tech Solutions runs that same engine in production today under two other products:

• PolyHealth - a multi-tenant healthcare-operations platform
• PulSe - a multi-tenant workforce-compliance platform

What CivicLoop inherits from that engine, working and hardened:

What is net-new for CivicLoop (the 9-day core build plus the 2026-05-18 wave):

• The 311 domain model (Document 03) - service requests, categories, routing rules, SLA policies, plus the visits / channels / surveys / forecasts tables from the second wave
• The resident intake surface - voice + text + photo + map pin - plus the public transparency portal at /public and the token-based survey at /survey/[token]
• The AI components tuned for 311 - intake parsing, auto-routing, SLA-breach prediction, sentiment/duplicate detection (Document 07) - plus the Loop channel persona, the Autopilot orchestrator, the predictive issue forecast, and the self-healing SLA escalator
• The agent console and the Director Dashboard for 311 specifically, plus the new console surface for scheduling visits, the /admin autopilot dial, the /council/[district] scoped dashboard, and the /channels Slack-style department rooms
• The geographic layer - maps, geocoding, service-area polygons, heat-map - plus the denormalized council_district / zip_code columns on locations and service_areas that power the equity, forecast, and council-view queries
• Open311 / GeoReport v2 conformance (Document 08), plus the public CSV export at /api/public/weekly.csv, the .ics calendar attachment endpoint at /api/visits/[id]/ics, the QR-code endpoint at /api/qr, and the self-heal cron endpoint at /api/cron/self-heal

This split is why a serious 311 product in nine days is realistic. Roughly half the system already exists and is in production; the team builds the 311-specific half on top.

1a. The 2026-05-18 lib modules

The 311-specific code is organized under web/src/lib/ so the boundaries are clean. Each module owns one concern, has its own RLS posture in the schema dump, and is independently testable.

Each module imports the same supabase-js service-role client, the same audit logger, and the same actor convention. Adding a tenth module follows the same shape.

2. The surfaces

CivicLoop is one system with three front-ends, all talking to the same core.

   RESIDENT SURFACE            STAFF CONSOLE              DIRECTOR DASHBOARD
  (web + installable           (web, desktop +           (web)
   mobile / PWA)                field-mobile)
        |                           |                          |
        |  voice / text / photo     |  queue, claim, work,      |  county-wide
        |  intake; track my         |  resolve-with-proof,      |  volume, SLA,
        |  requests; public map     |  override routing         |  heat-map, trends
        |                           |                          |
        +-------------+-------------+--------------+-----------+
                      |                            |
                      v                            v
            +-------------------------------------------------+
            |                CIVICLOOP CORE                  |
            |                                                 |
            |  Request lifecycle engine  |  AI components      |
            |  Routing + SLA engine      |  Notification engine|
            |  RBAC + tenant isolation   |  Audit logging      |
            |  Open311 API               |  Geo / mapping      |
            +-------------------------------------------------+
                      |                            |
                      v                            v
            +------------------+        +-------------------------+
            |  Data layer      |        |  External integrations  |
            |  (tenant-scoped, |        |  - SMS / WhatsApp / email|
            |   row-level      |        |  - Maps / geocoding     |
            |   security)      |        |  - MyPGC / govDelivery  |
            |                  |        |  - Open311 in/out       |
            +------------------+        +-------------------------+

• Resident surface - a Progressive Web App. No app-store install required (installs to the home screen on Android and iOS if the resident wants it). This matters: app-store friction and broken native apps are a documented 311 failure mode. A PWA also makes the offline story real.
• Staff console - web, optimized for desktop call-center / office use, but fully usable on a phone for field agents updating a request from the site of the work.
• Director Dashboard - web, presentation-grade, designed to be put on a screen in a leadership meeting.

3. Multi-tenant model

CivicLoop is multi-tenant from the data layer up. Prince George's County is one tenant. The architecture supports many.

• Every row in the system carries a county_id.
• Row-level security enforces tenant isolation at the data layer - a query physically cannot return another county's rows, regardless of application bugs.
• Each tenant has its own departments, categories, routing rules, SLA policies, staff, branding, supported languages, and integration configuration.
• Adding a second county is configuration and seed data, not a code fork.

Why a County panel should care: it means CivicLoop is not a bespoke one-off that rots after launch. It is a product with a roadmap, a shared codebase, and other deployments hardening it - the opposite of the abandoned-app failure mode (PublicStuff, PGC311).

4. Technology

The stack is the Ta-Tech engine's proven stack. The specifics matter less than the properties, but for the technical reviewer:

• Front-end: a modern React framework, server-rendered for speed and accessibility, Progressive Web App for the resident surface.
• Core / API: server-side application layer exposing both the internal API the surfaces use and the Open311 GeoReport v2 API for interoperability (Document 08).
• Data: a managed PostgreSQL database with PostGIS for the geographic layer (service-area polygons, nearest-X queries, the heat-map), and row-level security for tenant + role isolation.
• AI layer: large-language-model components for conversational intake, classification, and rationale generation; lightweight predictive models for SLA-breach forecasting and duplicate detection. Document 07 specifies each, including how each degrades safely when unsure.
• Hosting: a major cloud provider, US region only (Document 09 on data residency). Managed, monitored, backed up.
• Notifications: pluggable providers for SMS, WhatsApp, and email, plus a feed into the County's existing MyPGC / govDelivery channel.

5. The offline-first story (a real differentiator)

Most 311 systems assume a smartphone with a good connection. In a large, diverse county that is not always true - poor coverage areas, older devices, field workers in basements and dead zones, and the moments that matter most (storms, outages) are exactly when connectivity is worst.

CivicLoop is offline-capable by design, inherited from the engine:

• The resident PWA caches the application shell, the category tree, and the map tiles for the resident's area on first load.
• A resident can compose and submit a request offline - it queues on the device with its real timestamp and syncs the moment connectivity returns. The resident is told it is queued; they are not left wondering.
• A field agent can view their assigned requests, add progress notes, and attach proof photos offline; those sync on reconnection with the original timestamps preserved.
• For residents with no smartphone at all, the SMS channel is a first-class intake and notification path, not an afterthought.

We can say to the County, truthfully: residents can still report problems, and crews can still log work, during outages and in poor coverage. No competitor we surveyed does this convincingly.

6. Security architecture (summary - full detail in Document 09)

• Tenant isolation: row-level security at the data layer.
• Role isolation: the Document 04 RBAC model, enforced server-side.
• Auth: staff use email + password + TOTP two-factor; residents use passwordless one-time codes; SSO against the County identity provider is a supported configuration.
• Encryption: in transit (TLS) and at rest.
• Audit: immutable, attributable log on every meaningful action, including every AI decision.
• Data residency: US region only.
• Compliance path: architected to NIST 800-53 controls; StateRAMP / GovRAMP authorization pursued on the standard timeline while the pilot runs.

7. How it ships

CivicLoop uses the Ta-Tech engine's delivery pipeline:

• Type-checked builds - the build fails on type errors before anything deploys.
• Pre-deploy gate - a build must pass cleanly to be pushed.
• Automated deploy - to the hosted environment on merge.
• Hosted, versioned documentation - this very document set is built to a searchable hosted site the same way (Document 10).
• Schema discipline - one canonical schema, pulled fresh and audited before changes (a locked Ta-Tech practice).

For the pilot, this means changes the County asks for during the ninety days land quickly and safely, not in a quarterly release train.

8. Scalability and the platform path

CivicLoop v1 is scoped to 311 for one county. The architecture is deliberately built so the Phase 2 and Phase 3 path (Document 01, Section 9) is additive, not a rewrite:

• More counties - new tenants, no code fork.
• More agencies within a county - Health & Human Services, Schools, and the rest are new departments, new category trees, new surfaces - on the same core, the same RBAC, the same audit spine.
• The cross-agency layer - the Director Dashboard's county-wide view is the seam where the County Intelligence Platform grows. The domain model's clean Case seam (Document 03, Section 6) is where HHS plugs in.

The architecture is the moat: a competitor following us has to rebuild their core to be multi-tenant and cross-domain. CivicLoop starts there.

Next: 06 - Screens & User Flows.