CivicLoop by Ta-Tech Solutions All documents

04 - User Roles & Permissions

CivicLoop by Ta-Tech Solutions Purpose: Define every kind of user, what each can see and do, and the access-control model that keeps residents, County staff, and County leadership in their correct lanes.

---

1. The principle

CivicLoop has two populations of users with a hard wall between them:

• The public - residents. They see their own requests and the public map. Nothing else.
• County staff - everyone who works inside the system, in a tiered role model from frontline agent up to county administrator.

Access control is role-based, tenant-scoped, and least-privilege: a user sees the minimum needed to do their job, and never crosses the County (tenant) boundary. This model is inherited from the Ta-Tech engine, the same RBAC + row-level isolation that runs the healthcare and workforce platforms.

2. The roles

2.1 Resident (the public)

The member of the public. Can act with no account at all - a phone number is enough to file and be notified. An optional lightweight account adds a personal request history and saved locations.

A resident can:

• File a service request (voice, text, photo, map pin), in any supported language
• Track their own requests - status, timeline, comments, resolution proof
• Reply to an agent's "needs info" question
• Reopen their own request within the reopen window
• See the public map of requests (addresses generalized for privacy - see Document 09)
• Set language and notification-channel preference

A resident cannot:

• See another resident's personal details or private request content
• See any internal staff note or any staff-only field
• See routing rationale, SLA internals, or analytics
• Access any console or dashboard

2.2 Agent

Frontline County worker in a department - the person who resolves requests. The most-used staff role.

An agent can:

• See the queue of requests routed to their department
• Claim/self-assign a request, or work one assigned to them
• Move a request through the workflow: ASSIGNED -> IN PROGRESS -> NEEDS INFO -> RESOLVED
• Add progress updates, internal notes, and attachments (including the required proof-of-resolution photo)
• Comment to the resident (two-way thread)
• See the AI's routing rationale and override the routing (send to a different department) with a reason
• Flag a request as a duplicate or escalate it to a supervisor

An agent cannot:

• See requests routed to other departments (unless explicitly shared)
• Close a request (RESOLVED is theirs; CLOSED is a supervisor check in configurable strict mode, or automatic after the confirmation window)
• Change SLA policies, routing rules, categories, or staff
• See county-wide analytics beyond their own department

2.3 Supervisor

Leads a team of agents within a department.

A supervisor has everything an agent has, plus:

• See and manage all requests in their department, not just their own
• Assign and reassign requests across their agents
• Handle escalations (sentiment, safety, predicted SLA breach)
• Confirm/close RESOLVED requests in strict mode
• See their department's performance: volume, SLA compliance, agent workload, the department's slice of the heat-map
• Manage their department's agents (add, deactivate, reset access)

A supervisor cannot:

• Touch other departments' requests or staff
• Change county-level configuration (categories, the routing-rule catalogue, SLA policy library)

2.4 Department Head

Accountable for a whole department's service performance.

A department head has everything a supervisor has, plus:

• The full department view across all teams and supervisors
• Department-level SLA policy proposals (sent to the County Admin to ratify)
• Department staffing analytics and trend reporting
• The ability to define department business hours and the escalation contact

2.5 311 Director

Leads the Office of Community Relations / the 311 function. The cross-department view.

A 311 Director can:

• See every request across every department - the whole County
• Open the Director Dashboard: county-wide volume, category mix, SLA performance, the full geographic heat-map, trend lines, language-served breakdown
• See cross-department routing patterns and re-routing rates (is the AI routing well?)
• Pull and export reports (including the public open-data export)
• Raise a cross-department escalation
• See, but not unilaterally change, county configuration

A 311 Director is the primary audience for the system's intelligence - the person who manages the system rather than the queue.

2.6 County Admin

The top staff role. The configuration owner. Held by very few people.

A County Admin can do everything a 311 Director can, plus:

• Manage the service category tree and their default routing + SLA
• Manage the routing-rule catalogue
• Manage the SLA policy library
• Manage departments and all staff across all departments, including role assignment
• Manage County branding, supported languages, notification templates
• Configure integrations (Open311 endpoint, MyPGC/govDelivery feed, SMS/WhatsApp/email providers, maps)
• Grant time-limited permission grants (give one person one extra capability for a defined window - inherited from the Ta-Tech engine)
• See the full audit log

A County Admin cannot quietly do harm without a trace: every configuration change writes an immutable Audit Log entry.

New 2026-05-18 capabilities on the County Admin surface (/admin):

• Set the Autopilot dial. One control with three positions - off, route, full. Writes counties.autopilot_level. Every flip is audit-logged. The dial governs how much the AI does on its own at intake (Document 07, Component J).
• Run self-heal now. A "Run now" button next to the dial that fires the self-heal sweep on demand (Document 07, Component L): finds open requests with breached or near-breach SLA, reassigns them to a supervisor in the same department, bumps priority, posts a @first-name heads-up in the department channel, and notifies the resident. Idempotent (6-hour cooldown per request).
• Build location posters. /admin/locations lets the County admin generate a printable poster with a QR code for any council district, kiosk, or known problem area. The QR encodes /report?address=&lat=&lng= so a scan auto-fills the report flow. The poster is a branded PDF (Document 08).

2.6b The new role-scoped surfaces

Surface	Owned by	Notes
/admin autopilot dial + self-heal Run now + location posters	County Admin	Audit-logged. Self-heal is also reachable as the cron endpoint /api/cron/self-heal (Document 08), gated by the optional SELFHEAL_CRON_TOKEN env.
/dashboard forecast panel "Run forecast now"	311 Director (and County Admin, who inherits the Director surface)	Director-triggered. Writes one row per (category, council_district) into predicted_issues.
/dashboard equity panel	311 Director	Read-only view; the data comes from service_areas.council_district and locations.council_district.
/dashboard upcoming visits panel	311 Director and the department's Supervisor / Department Head (scoped)	Reads scheduled_visits for the staffer's scope.
/console/[requestNumber] schedule visit + visits list	Agent and above	Creating a visit fires SMS + email with a .ics attachment to the resident. Cancel + complete write Request Events.
/channels and /channels/[slug]	Any staff member (department channel visible to its department, #311-all to everyone)	Slash commands (/help, /open, /breaches, /summary CP-...) are deterministic - no AI call. @loop triggers the AI persona (Document 07).
/council/[district]	A council member or their staff, plus 311 Director and County Admin	The view is scoped to one of PG County's 9 districts. Shows totals, open, resolved, SLA breaches, top categories, recent requests, and the district's slice of the forecast. Council-member sign-in is a future seam; for the pilot, the County Admin grants the access.
/survey/[token]	Resident (the original requester only; token is single-use)	No auth, no PII, no account. The token IS the credential.
/public	Anyone, anywhere, no account	NOT locale-scoped; one URL. Shows aggregated last-7-day numbers and an anonymized SVG scatter map. CSV at /api/public/weekly.csv.

2.7 System / AI (not a person)

The AI components and background jobs act under a system identity. Every action they take - classify, route, predict, notify - writes an AI Decision and/or Audit Log row attributed to "ai" or "system," never to a person. This keeps the human audit trail clean and the AI accountable.

3. The permission matrix

R = Resident, A = Agent, S = Supervisor, DH = Department Head, D = 311 Director, CA = County Admin.

Capability	R	A	S	DH	D	CA
File a service request	Y	Y	Y	Y	Y	Y
Track own requests	Y	Y	Y	Y	Y	Y
See public map	Y	Y	Y	Y	Y	Y
See own department's queue	-	Y	Y	Y	Y	Y
Claim / work a request	-	Y	Y	Y	Y	Y
Move workflow to RESOLVED	-	Y	Y	Y	Y	Y
Override AI routing (with reason)	-	Y	Y	Y	Y	Y
Comment to resident	-	Y	Y	Y	Y	Y
Close (confirm) a request	-	-	Y	Y	Y	Y
Reassign across agents	-	-	Y	Y	Y	Y
Handle escalations	-	-	Y	Y	Y	Y
See whole-department analytics	-	-	Y	Y	Y	Y
Manage department staff	-	-	partial	Y	-	Y
Set department hours / SLA proposals	-	-	-	Y	Y	Y
See ALL departments' requests	-	-	-	-	Y	Y
Director Dashboard (county-wide)	-	-	-	-	Y	Y
Export reports / open-data	-	-	-	-	Y	Y
Manage categories / routing rules	-	-	-	-	-	Y
Manage SLA policy library	-	-	-	-	-	Y
Manage departments & all staff	-	-	-	-	-	Y
Configure integrations	-	-	-	-	-	Y
Time-limited permission grants	-	-	-	-	-	Y
See full audit log	-	-	-	-	partial	Y
Schedule a visit on a request	-	Y	Y	Y	Y	Y
Upload progress photo (in assigned or in_progress)	-	Y	Y	Y	Y	Y
Post in department channels	-	Y	Y	Y	Y	Y
@loop the AI persona in a channel	-	Y	Y	Y	Y	Y
Open /council/[district] scoped view	-	-	-	-	Y	Y
Open /public transparency portal	Y	Y	Y	Y	Y	Y
Receive auto-survey + answer it	Y	-	-	-	-	-
Set the Autopilot dial (off/route/full)	-	-	-	-	-	Y
Run self-heal "Run now" (admin)	-	-	-	-	-	Y
Run "Run forecast now" (director)	-	-	-	-	Y	Y
Build location-poster QR	-	-	-	-	-	Y

"partial" = scoped: a Supervisor manages only their own agents; a 311 Director sees audit entries for requests, not for county configuration.

4. Authentication

Population	How they sign in
Residents	Phone number + one-time SMS code, or email + one-time code. Optional: set a PIN for faster re-entry. No password to forget - this directly fixes the documented "password loop" failure mode. Anonymous filing needs no sign-in at all.
County staff	County email + password + two-factor (TOTP). Two-factor is mandatory for all staff roles - this is government data. Trusted-device option remembers a browser for 30 days. SSO against the County's identity provider is supported as a configuration option (Document 05).

5. Why this model is defensible to a County panel

• Least privilege, demonstrably. The matrix above is the actual enforced model, not aspirational. A panel can read it and see that an agent in DPWT cannot see a Health & Human Services request - the kind of cross-department leakage that worries privacy reviewers.
• The public/staff wall is hard. Residents have no path to any console. There is no "view as" trapdoor.
• Every privileged action is audited. County Admin power is real but never silent - the Audit Log is immutable and attributable.
• The AI has an identity and a record. It is not an invisible hand; every decision it makes is attributed and reviewable.
• It is built, not promised. This is the Ta-Tech engine's RBAC + tenant isolation, already running in production on the healthcare and workforce platforms. CivicLoop inherits it; it is not a 9-day invention.

---

Next: 05 - System Architecture.