AWS Builder Center
CivicSOS: Building an Autonomous Civic Resolution Agent on AWS

CivicSOS: Building an Autonomous Civic Resolution Agent on AWS

CivicSOS turns messy civic complaints into an actionable resolution workflow-from understanding the problem and preparing evidence to approval, submission, tracking, and follow-up. Here’s how I built and deployed it on AWS during First Commit.

Series: First Commit (1 article)

  1. 1
    CivicSOS: Building an Autonomous Civic Resolution Agent on AWS This article
student
CivicSOS: From “Where Do I Complain?” to “It’s Being Handled” — Building an Autonomous Civic Resolution Agent on AWS
The Problem
A pothole. An overflowing garbage bin. A broken streetlight. A water complaint.
Reporting these problems sounds simple.
But the actual process often looks like this:
  • Who handles this?
  • Where do I complain?
  • What information do I need?
  • What should I write?
  • Which form should I use?
  • What happens after I submit?
  • When should I follow up?
The information may already exist online.
The problem is the workflow.
Citizens are forced to become the workflow engine.
That is the problem I wanted to solve with CivicSOS.
Tell CivicSOS what happened. CivicSOS handles the rest.
From Civic Directory to Civic Resolution Agent
The first version of the idea was straightforward: help citizens find the right place to report a civic problem.
Then came the uncomfortable question:
Why would someone use CivicSOS if they can just Google where to complain?
That question changed the project completely.
CivicSOS became an autonomous civic resolution agent.
Instead of simply telling someone where to complain, CivicSOS is designed to take a citizen from:
“Something is wrong.”
to:
“My complaint is prepared, the supported workflow is ready, my case is tracked, and I know what happens next.”
The core workflow is:
Problem → Understanding → Evidence → Authority → Complaint → Approval → Action → Reference → Tracking → Follow-up → Escalation
The goal isn’t unrestricted AI autonomy.
The goal is useful autonomy with explicit human control.
What Happens When Someone Reports a Problem?
Imagine someone says:
“Garbage has not been collected outside my apartment for 5 days.”
They can attach a photograph and location.
CivicSOS turns that natural-language report into structured case information:
  • Category
  • Location
  • Duration
  • Description
  • Evidence
  • Authority
  • Required action
  • Complaint text
  • Case state
The citizen shouldn’t need to understand the administrative structure first.
The system starts with the problem and works toward the resolution workflow.
The Agent Is More Than a Chatbot
CivicSOS doesn’t give an LLM unrestricted access to external systems.
The agent core uses 13 named actions and fixed, ordered plans.
Each action passes through a policy gate based on persisted case state and the knowledge layer.
Most importantly:
Approval is a hard boundary.
Without explicit approval, consequential acting steps are refused.
This makes the agent easier to:
  • Test
  • Reason about
  • Audit
  • Demonstrate safely
The architecture deliberately separates understanding and planning from consequential actions.
The Official-Channel Workflow
One of the biggest improvements during development was closing the gap between:
“Here is the official website.”
and:
“I actually helped you use it.”
CivicSOS therefore includes an official-channel browser-assist workflow.
After the complaint is prepared, the user can hand off to a supported official-channel workflow.
The intended experience is:
CivicSOS → Verified official channel → User authentication → Browser-assisted form preparation → User review → Final submission by citizen
There are deliberate boundaries.
CivicSOS does not:
  • Collect government passwords
  • Bypass authentication
  • Bypass OTP
  • Bypass CAPTCHA
  • Impersonate the citizen
  • Automatically perform the final consequential submission
The citizen remains in control of sensitive actions.
Browser Assist: Demonstrating What the Agent Refuses to Do
A browser assistant is useful only if its boundaries are observable.
Instead of pretending to have a verified integration with every government portal, CivicSOS includes a controlled practice portal specifically for demonstrating the browser-assist workflow.
The practice portal is clearly labelled:
CivicSOS Practice / Demo Portal — Not a Government Website
The browser assistant demonstrates how CivicSOS can:
  • Receive a prepared case
  • Map case data to form fields
  • Autofill supported fields
  • Pause for authentication
  • Leave OTP and CAPTCHA untouched
  • Stop before final submission
The extension mapping contains only selectors that can actually be verified.
The build process also validates those selectors against the practice portal.
I deliberately tested this by renaming a selector and confirming that the build fails.
That means the browser integration isn’t based on:
“Trust me, these selectors work.”
It is based on:
“The build verifies that they still work.”
For real government portals, integrations require a separately verified channel and current portal compatibility rather than assuming that practice-portal selectors will work everywhere.
Manual Submission Tracking
There was another subtle problem in the official-channel workflow.
If a citizen submits a complaint themselves, CivicSOS needs to distinguish that from a simulated submission.
The case model therefore records the submission mode.
For manual submissions, CivicSOS allows the citizen to enter the reference number received from the official website.
The interface clearly communicates that this reference is user-provided.
This closes the loop without pretending that CivicSOS performed an action it did not perform.
Demo Mode Is Explicitly a Demo
For hackathon demonstrations, CivicSOS also has a deterministic submission environment.
A simulated submission generates references such as:
CS-DEMO-93722
and records:
submissionMode: SIMULATED
The interface also makes the simulated nature visible.
This is important because CivicSOS should never claim that a government complaint was actually submitted when it wasn’t.
The AWS Architecture
CivicSOS is deployed as a production-style AWS application rather than a local-only prototype.
The live application uses:
Next.js → AWS Amplify Hosting → Cognito → WAF → API Gateway → Lambda → DynamoDB / S3 / EventBridge
Additional infrastructure supports configuration, monitoring and browser-assisted workflows.
Frontend
The Next.js application is deployed on AWS Amplify Hosting with SSR support.
Authentication
Amazon Cognito handles authentication and protected application access.
API and Security
Requests pass through:
AWS WAF → API Gateway → Lambda
The backend is protected with authentication, authorization and rate-limiting controls.
Core Backend
AWS Lambda handles:
  • User/authentication operations
  • Case management
  • Agent orchestration
  • Submission workflows
  • Follow-ups
  • Escalation logic
Data
DynamoDB stores:
  • Case state
  • Agent workflow state
  • Submission references
  • Follow-up information
  • Distributed rate-limit state
Amazon S3 stores evidence such as photographs and documents with public access blocked.
Event-Driven Workflows
Amazon EventBridge handles asynchronous events and workflow triggers for follow-up and related background processes.
Configuration and Monitoring
AWS Systems Manager Parameter Store manages configuration values.
Amazon CloudWatch provides:
  • Logs
  • Monitoring
  • Alarms
  • Operational visibility
Browser-Assisted Workflows
For supported workflows, browser execution is isolated from the core API using a containerized Playwright + Chromium workload designed around ECS Fargate.
The browser workflow is intentionally separated from the Lambda core because browser runtimes have different dependencies and security considerations.
Sensitive actions remain human-controlled.
Why Amplify Instead of CloudFront?
During deployment, CloudFront was initially considered as an additional edge layer.
However, the AWS account required verification before new CloudFront resources could be created.
Rather than waiting for account verification and delaying deployment, I used AWS Amplify Hosting for the Next.js application.
The first Amplify deployment returned 404s because the application was initially configured for static hosting rather than Next.js SSR.
I traced the issue to the hosting configuration, switched the application to WEB_COMPUTE / Next.js SSR, restored the required environment variables, and successfully redeployed and validated the application.
This resulted in a working live deployment without making CloudFront a dependency for the hackathon release.
Why DynamoDB Instead of Redis?
Redis was considered for distributed rate limiting.
The actual requirement was relatively simple:
Prevent excessive requests across Lambda instances.
A DynamoDB conditional update provides an atomic shared counter with TTL-based expiry.
Production testing confirmed the shared limiter.
This avoided introducing a VPC-dependent cache layer purely for a simple rate-limiting requirement.
Redis would make more sense for workloads requiring things such as complex sliding-window calculations or extremely high-frequency low-latency shared state.
The lesson:
Don’t add infrastructure because it looks impressive. Add it because the problem requires it.
Why Not EKS?
EKS was also considered for browser-agent execution.
But the question wasn’t:
“Can we use Kubernetes?”
The question was:
“What problem would Kubernetes solve here?”
The browser assistant deliberately does not handle government credentials or bypass authentication and CAPTCHA.
Running a permanent Kubernetes environment for a constrained browser workflow would add significant infrastructure complexity without solving the core problem.
Instead, browser execution is isolated into a dedicated container workload.
Security Was Designed Into the System
Civic applications can contain sensitive information such as photographs, locations and complaint history.
Security was therefore treated as part of the architecture rather than a final checklist.
Production verification includes:
Authentication
Protected application routes require authentication.
Authorization
Cross-user case access is rejected.
Evidence Protection
S3 public access is blocked.
Agent Approval
Acting operations without explicit approval are rejected.
Credential Safety
The browser assistant is explicitly designed not to collect or store government credentials.
Human-Controlled Security Boundaries
Authentication, OTP, CAPTCHA and final official submission remain under citizen control.
Testing the System
I didn’t want CivicSOS to work only during one successful demo.
The project currently has:
216 automated tests passing
The project also passes:
  • TypeScript type checking across five workspaces
  • Linting
  • Production builds
  • OpenAPI validation
  • CDK synthesis
  • Browser workflow testing
  • Production smoke testing
The production workflow has been validated across:
  • Case creation
  • Agent execution
  • Approval gates
  • Submission workflows
  • Case tracking
  • Follow-up preparation
  • Escalation logic
  • Authentication
  • Authorization
  • Evidence handling
One example of why this matters:
An overdue case previously had two conflicting definitions of its follow-up date.
The header said one thing.
The workflow step said another.
That inconsistency was fixed and covered with tests.
The escalation workflow was also corrected so escalation cannot accidentally appear on the same day as the follow-up when configured windows overlap.
These are small details, but they are exactly the kind of bugs that can make an autonomous system feel unreliable.
What Fought Back
The hardest parts weren’t necessarily writing code.
They were the assumptions that broke once the project became a real cloud application.
CloudFront Account Verification
The initial edge deployment encountered an AWS account-level restriction requiring verification before new CloudFront resources could be created.
Instead of pretending the deployment was complete, I opened an AWS Support case and moved forward with Amplify Hosting for the production frontend.
That experience highlighted an important difference between local development and real cloud infrastructure:
Cloud infrastructure has operational constraints that don’t exist in local development.
Another Lesson: Autonomous Doesn’t Mean Uncontrolled
The goal of CivicSOS was never:
“Give AI access to everything.”
The goal was:
“Automate the repetitive work while keeping consequential decisions visible to the human.”
That principle affects every major workflow.
The citizen controls:
  • Approval
  • Authentication
  • OTP
  • CAPTCHA
  • Final official submission
  • Sensitive decisions
CivicSOS handles the repetitive work surrounding those boundaries.
Technology Stack
Frontend
  • Next.js
  • TypeScript
  • Responsive web UI
  • AWS Amplify Hosting
Backend
  • AWS Lambda
  • API Gateway
  • DynamoDB
  • S3
  • EventBridge
  • Cognito
Security & Monitoring
  • AWS WAF
  • CloudWatch
  • SSM Parameter Store
Browser Automation
  • Docker
  • Playwright
  • Chromium
  • ECS Fargate for supported browser workflows
Infrastructure
  • AWS CDK
  • OpenAPI
  • Automated testing
Agent
  • Deterministic agent orchestration
  • Policy-gated actions
  • Structured case state
  • Natural-language understanding
Development
  • Claude Code
  • Claude Opus
  • GitHub
AI coding tools were used during development, while the architecture, security boundaries, implementation decisions and verification were handled as part of the project.
What I Learned
The biggest lesson wasn’t about Lambda, DynamoDB, Amplify, containers or AWS services.
It was:
Architecture should follow the problem.
During a hackathon, it’s tempting to think:
“We need EKS.” “We need Redis.” “We need an LLM everywhere.” “We need more AWS services.”
But every additional component introduces complexity.
The better question is:
What problem does this component solve?
That question kept Lambda as the core execution layer.
It made DynamoDB sufficient for distributed rate limiting.
It led to containers specifically for the browser workload.
It prevented unnecessary Kubernetes infrastructure.
And it pushed the agent toward explicit, testable actions instead of unrestricted automation.
What’s Next?
The next stage is expanding the official-channel experience through verified real-world integrations where appropriate.
The long-term workflow is:
Citizen reports → CivicSOS understands → evidence is checked → complaint is prepared → citizen approves → supported channel is opened → browser assistance helps prepare the form → citizen authenticates/reviews → citizen submits → CivicSOS tracks and follows up
The objective isn’t to replace government systems.
It is to build the missing layer between:
“I have a problem.”
and
“I know what to do next.”
Final Thought
A pothole doesn’t look like a software problem.
Neither does an overflowing garbage bin.
Neither does a broken streetlight.
But once a citizen has to figure out:
  • Who handles this?
  • What evidence do I need?
  • Which form do I use?
  • What do I write?
  • Where do I submit it?
  • What happens after I submit?
  • When should I follow up?
…it becomes a workflow problem.
CivicSOS is an attempt to make that workflow disappear.
Tell CivicSOS what happened. CivicSOS handles the rest.
Project
AWS deployment: AWS Amplify Hosting + Cognito + WAF + API Gateway + Lambda + DynamoDB + S3 + EventBridge + CloudWatch + SSM Parameter Store, with containerized browser-assist infrastructure for supported workflows.

Series: First Commit (1 article)

  1. 1
    CivicSOS: Building an Autonomous Civic Resolution Agent on AWS This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article