Imported from Sabari-Vijayan/Member-Bot (AGENTS.md). Install upstream with npx skills add Sabari-Vijayan/Member-Bot. Copyright stays with the author.

AGENTS.md — AI Initialization & Context Guide

This document serves as the primary context initialization file for AI agents (Antigravity, Claude Code, Cursor, Copilot, etc.) working on the Ward Complaint System (Public Prototype).

1. Executive Summary & Vision

The Ward Complaint System is an automated grievance tracking and ward management platform built for Local Self Government (LSG) bodies in Kerala, India (covering Panchayats, Municipalities, and Corporations across all 14 districts).

Core Features:

• Citizen "Front Door": Citizens submit hyper-local complaints (garbage disposal, streetlight outages, pothole repair, drainage, water supply) via WhatsApp (or SMS/Telegram) without registering or logging in. Supports English and Malayalam (ml).
• Ward Member Dashboard: A web portal for elected LSG ward members and admins to view, assign, respond to, track SLAs, and resolve complaints submitted in their ward.
• K-SMART Complementary Architecture: Designed specifically as a complementary micro-service to Kerala's K-SMART platform (owns day-to-day ward-level issues, keeps data portable via external_reference_id, and avoids proprietary lock-in).

2. Codebase Directory Map

solver-for-public-prototype/
├── AGENTS.md                       # This AI initialization & context guide
├── README.md                       # High-level project entry point
├── ward-complaints/                # Primary application code
│   ├── server/                     # Elixir / Phoenix backend API & Webhook handler
│   │   ├── config/                 # Phoenix configuration (dev, test, prod, runtime)
│   │   ├── lib/
│   │   │   ├── ward_complaints/    # Business logic, Repos, Workers, GenServers
│   │   │   │   ├── application.ex  # Application supervision tree
│   │   │   │   ├── repo.ex         # Ecto Repo interface
│   │   │   │   └── conversations/  # Conversation state machine & registries
│   │   │   └── ward_complaints_web/ # Phoenix HTTP router & controllers
│   │   │       ├── router.ex       # API routing (/api/gateways/whatsapp, /api/whatsapp/webhook)
│   │   │       └── gateways/       # WhatsappWebhookController, CacheBodyReader, WhatsappSender
│   │   └── mix.exs                 # Mix dependencies & build configuration
│   ├── frontend/                   # React + Vite web dashboard for Ward Members & Admins
│   │   ├── src/
│   │   │   ├── components/         # UI components
│   │   │   ├── pages/              # Dashboard pages (Complaints list, details, stats)
│   │   │   └── lib/                # API client & Supabase auth helpers
│   │   └── package.json
│   ├── db/                         # Production SQL schemas & Row-Level Security
│   │   ├── schema.sql              # Database DDL & table definitions
│   │   └── rls_policies.sql        # Supabase Postgres Row-Level Security policies
│   └── docs/                       # Project documentation
│       ├── howtorun.txt            # Local server & webhook setup instructions
│       └── whatsapp_flow_plan.md   # State machine plan for citizen WhatsApp conversations
├── database_schema/                # Iterative SQL drafts & final schema reference
│   ├── final.txt                   # Complete schema reference (Districts, Wards, Citizens, Complaints)
│   └── rls.txt                     # Comprehensive RLS policies and indexes
├── openwa/                         # Open-WhatsApp NestJS SDK / API reference integration
│   └── OpenWA/                     # OpenWA docker & NestJS codebase
├── whatsapp_integration/           # Meta WhatsApp Cloud API credentials & curl test scripts
│   └── first_test/                 # Test scripts & Meta API token samples
└── suggestions/                    # Architectural notes on Supabase resilience & K-SMART alignment

3. Database Schema Overview

The database is built on PostgreSQL (designed for deployment on Supabase or self-hosted Postgres):

4. Backend Architecture (Elixir / Phoenix)

The backend (ward-complaints/server) is implemented using Elixir / Phoenix:

1. Webhook Endpoint Routing (WardComplaintsWeb.Router)

• GET /api/gateways/whatsapp & GET /api/whatsapp/webhook: Meta Webhook Verification challenge (WhatsappWebhookController.verify/2).
• POST /api/gateways/whatsapp & POST /api/whatsapp/webhook: Message payload ingestion (WhatsappWebhookController.receive_message/2).

2. Webhook Security & Verification (WhatsappWebhookController)

• Challenge Verification: Uses Plug.Crypto.secure_compare/2 against WHATSAPP_VERIFY_TOKEN.
• HMAC Signature Check: Validates x-hub-signature-256 or x-openwa-signature against WHATSAPP_APP_SECRET using raw request body preserved by CacheBodyReader. Controlled locally via VERIFY_WHATSAPP_SIGNATURE="true".

3. Payload Normalization & Async Offloading

• Supports both Meta Cloud API and OpenWA payload structures.
• Offloads processing asynchronously via Task.start/1 to respond with 200 OK instantly, preventing webhook timeouts.
• Dispatches messages to WardComplaints.Conversations.ConversationSupervisor via WardComplaints.ConversationRegistry.

5. Development Setup & Execution

Prerequisites

• Elixir 1.14+ & Erlang/OTP
• Node.js 18+
• PostgreSQL / Supabase
• Ngrok (for local Meta WhatsApp webhook testing)

Environment Variables

Set these variables before launching the server:

export WHATSAPP_VERIFY_TOKEN="your_verify_token"
export WHATSAPP_APP_SECRET="your_meta_app_secret"
export WHATSAPP_TOKEN="your_meta_system_user_token"
export WHATSAPP_PHONE_NUMBER_ID="your_whatsapp_phone_number_id"
export VERIFY_WHATSAPP_SIGNATURE="false" # set true in production

Running Backend Server

cd ward-complaints/server
mix deps.get
mix phx.server
# Server runs at http://localhost:4000

Running Frontend Dashboard

cd ward-complaints/frontend
npm install
npm run dev

Testing Webhooks Locally

ngrok http 4000
# Register Callback URL in Meta Portal: https://<ngrok-id>.ngrok-free.app/api/gateways/whatsapp

6. AI Development Rules & Guidelines

When generating code or refactoring this project, AI agents MUST follow these guidelines:

1. Row-Level Security (RLS) Compliance: Always respect ward isolation in database queries. Staff members (ward representatives) must only have read/write access to complaints within their assigned ward_id. Admins have global access.
2. Supabase Abstraction Layer: Wrap all Supabase or third-party database calls inside dedicated Elixir context modules (e.g., WardComplaints.Complaints, WardComplaints.Citizens) to allow easy swapping or self-hosting if necessary.
3. Payload Compatibility: Maintain support for both Meta Cloud API webhooks and OpenWA payloads in WhatsappWebhookController.
4. K-SMART Interoperability: Always include external_reference_id when designing complaint schema extensions or API payloads to facilitate future government integration.
5. No Direct State Mutation: Use Elixir GenServer / Task supervisors for managing conversation states per citizen phone number.

Generated for AI Assistant Context Initialization — Ward Complaint System.