🏛️ Smart Grievance System

AI-powered citizen complaint management platform built entirely on AWS serverless infrastructure.

---

☁️ AWS Services Used

Service	Purpose	Resource ID
CloudFront	CDN — HTTPS frontend delivery	EEO2L0440ORJG
S3 (Frontend)	Hosts React build files	grievance-app-test-frontendbucket-txiaeh8iwzxk
S3 (Attachments)	Stores user-uploaded files	grievance-app-test-attachmentsbucket-9sn2uwashkmf
S3 (Analytics)	Analytics data exports	auto-generated
DynamoDB (Complaints)	Main complaints database	grievance-app-test-ComplaintsTable-149EFFYK8SRJJ
DynamoDB (Audit)	Change audit trail	grievance-app-test-AuditLogTable-1WP32UU92ZZLT
Cognito	Authentication + role groups	ap-south-1_sTP6qFtt8
API Gateway	REST API with JWT auth	srq4zwhl32
Lambda × 7	All business logic (Node.js 20)	see below
SNS	Alert notifications	grievance-app-test-complaint-alerts
VPC + NAT	Private network for Lambdas	vpc-019aa34c651b13dad
CloudWatch	Lambda logs + VPC flow logs	/aws/lambda/...
EventBridge	Scheduled SLA escalation (15 min)	auto
Glue + Athena	Analytics SQL pipeline	grievance-app-test_analytics

---

⚡ Lambda Functions

Function	Route	Role
CreateComplaintFunction	POST /complaints	Submit new complaint
GetMyComplaintsFunction	GET /complaints/me	Citizen's own complaints
GetComplaintByIdFunction	GET /complaints/{id}	Single complaint detail
UpdateComplaintStatusFunction	PATCH /complaints/{id}/status	Admin status update
GetAttachmentPresignUrlFunction	POST /attachments/presign	S3 upload URL generator
GetAnalyticsOverviewFunction	GET /analytics/overview	Admin KPI dashboard
EscalateOverdueComplaintsFunction	(scheduled every 15 min)	Auto-SLA escalation

---

🗄️ Data Schema

Complaints Table (DynamoDB)

{
  "id": "uuid-v4 (PK)",
  "userSub": "cognito-user-id (GSI: UserSubIndex)",
  "userEmail": "citizen@email.com",
  "issue": "Pothole on main road",
  "category": "Infrastructure",
  "department": "Infrastructure",
  "status": "Pending | In Progress | Resolved | Rejected",
  "sentiment": "NEUTRAL | POSITIVE | NEGATIVE",
  "timestamp": "2026-04-27T18:30:00.000Z",
  "slaDueAt": "2026-04-30T18:30:00.000Z",
  "escalationLevel": 0,
  "attachment": {
    "fileName": "photo.jpg",
    "s3Key": "complaints/2026-04-27/uuid-photo.jpg",
    "contentType": "image/jpeg",
    "size": 139264
  }
}

Audit Log Table (DynamoDB)

{
  "complaintId": "uuid-v4 (PK)",
  "auditTs": "ISO timestamp (SK)",
  "action": "STATUS_UPDATED | COMPLAINT_CREATED | ESCALATED",
  "actor": "admin@email.com",
  "actorRole": "ADMIN | SYSTEM",
  "details": {
    "fromStatus": "Pending",
    "toStatus": "In Progress"
  }
}

---

🚀 Deployment

Backend

cd infrastructure
sam build
sam deploy --stack-name grievance-app-test \
  --capabilities CAPABILITY_IAM \
  --parameter-overrides 'AppName="grievance-app-test" Region="ap-south-1" NotificationEmail="your@email.com"'

Frontend

cd frontend
npm run build
aws s3 sync dist/ s3://grievance-app-test-frontendbucket-txiaeh8iwzxk --delete
aws cloudfront create-invalidation --distribution-id EEO2L0440ORJG --paths "/*"

---

🔑 Test Credentials

Role	Email	Password
Admin	hruthiktej86@gmail.com	Admin@12345

---

💰 Monthly Cost Estimate

Service	Cost
2× NAT Gateway	~$130
Application Load Balancer	~$20
All other services	~$5
Total	~$155/month

Remove the VPC from template.yaml after demo to drop cost to ~$0/month.

---

🏗️ Tech Stack

• Frontend: React 18 + Vite + Framer Motion + TailwindCSS
• Backend: AWS Lambda (Node.js 20) + AWS SAM
• Database: Amazon DynamoDB (Pay-per-request)
• Authentication: Amazon Cognito (User Pools + Groups)
• Storage: Amazon S3 (Presigned URLs)
• API Layer: Amazon API Gateway
• Notifications: Amazon SNS
• Monitoring: Amazon CloudWatch
• Scheduling: Amazon EventBridge
• Analytics: AWS Glue + Amazon Athena
• Infrastructure as Code: AWS SAM (CloudFormation)

---

✨ Features

• Citizen complaint submission with attachments
• Secure authentication using Cognito JWT tokens
• Role-based access (Citizen/Admin)
• Complaint status tracking
• Automated SLA monitoring and escalation
• Audit logging for transparency
• Analytics dashboard for administrators
• Serverless architecture with minimal operational overhead
• Direct S3 uploads using presigned URLs
• Real-time notification workflow using SNS