Admin Console — Spec

This page is the design specification for the CivicPulse admin console — the operator-facing application that runs moderation, triage, configuration, and platform administration for CivicPulse India. It originated as a design brief intended for producing mockups, and intended to also serve as the build spec. It documents intended structure and scope; treat sections describing screens or behavior that aren't yet implemented as design intent rather than a guarantee of current behavior — check the Overview and the codebase itself for what actually exists today.

The admin console is a separate application from the public CivicPulse site, with its own admin authentication and a dense, operator-focused UI (as opposed to the public site's editorial/marketing style).

1. Product context

CivicPulse is a civic-accountability platform for Indian cities (Mumbai is live; more cities are in rollout). Citizens report civic issues (potholes, garbage, unsafe streets, etc.) via the platform itself or through WhatsApp, Instagram, or X. Each report is auto-routed by ward and pincode to the office responsible for it — office names are used rather than individual officials' names by design, since the product holds the office accountable, not the person.

A 48-hour SLA (service-level agreement — a 48-hour window after which an issue auto-escalates if not resolved or acknowledged) starts on each report. If the SLA is missed, the issue auto-escalates up an accountable chain (Corporator → BMC Ward Officer → MLA → MP), and every delay is public. Wards, officials, and citizen reporters all get 0–100 accountability scores. The platform also has a community events section (clean-ups, plantation drives, awareness walks) run by NGOs and citizens.

The admin console is the operator surface that runs all of this: moderating the public feed, triaging multi-channel intake, configuring policy, managing integrations, and administering the platform.

2. Framing & constraints

• Separate app, separate deploy — e.g. admin.civicpulseindia.com.
• Separate admin authentication with RBAC (role-based access control) and 2FA (two-factor authentication) — distinct from the public citizen login.
• Backed by the same backend, under an /admin API namespace.
• Not the editorial/marketing style of the public site. This is a dense, utilitarian operator console: persistent left nav, data tables with filters and bulk actions, detail/inspector drawers, review queues, and configuration forms.
• Multi-tenant — a global city switcher scopes almost every screen to one city.
• Everything is RBAC-gated and audited.

Design system to reuse

• Colors: ink #0F1115, accent #FB4A2E (hover #E23A1F).
  • Status system: new #9AA2AF, acknowledged #F5A300, in-progress #2563EB, resolved #10B981, overdue #EF4444.
  • Grade scale: A #0F9D57, B #22A866, C #E5A000, D #F2740B, E #EF4444.
• Fonts: Space Grotesk (display), Plus Jakarta Sans (body), Space Mono (labels/metadata/IDs).
• Reusable atoms: status pills, grade badges, avatars — carried over from the public app but laid out for density.
• Light and dark themes.

Global chrome (every screen)

City switcher, global search, notifications bell, admin profile menu, and a visible/accessible audit trail. RBAC hides sections and actions the current admin can't use.

3. Roles

Role	Scope
super-admin	All cities, all sections, RBAC + system ops
city-admin	Everything, scoped to a single city
reviewer	Moderation queues only (feed, flags, applications)
auditor	Read-only, including the audit log

4. Sections (information architecture)

0. Dashboard

Per-city at-a-glance view: open issues, overdue / SLA-breached now, escalations armed, average first-response time, resolution rate, reports today/this week, intake backlog (unreviewed), pending reporter applications, and open flags. Includes trend sparklines and a "Needs attention" column (breaches, flagged content, stuck items) that deep-links into the relevant queue.

1. Feed Management & Review (priority pillar)

The moderation and triage heart of the console.

• Intake triage queue — incoming reports (from the platform, WhatsApp, Instagram, or X) awaiting review or auto-created. Actions: publish, correct the auto-routing (category, ward, pincode, or responsible office), merge duplicates, reject/spam, request more info. Supports bulk actions.
• Issue moderation — inspect any issue in a detail drawer (full accountability chain, activity log, media, map). Actions: edit metadata, change status (audited), reassign in chain, force-escalate / pause SLA, close/reopen, unpublish/hide, pin/feature, redact media (mask faces, plates, phone numbers).
• Flags queue — user-reported issues, comments, media, and reporters, grouped by reason. Actions: dismiss, warn, remove, ban.
• Comments & media moderation — remove abusive messages (soft-delete); review flagged/suspicious media with an EXIF/GPS panel.
• Duplicate clusters — near-duplicate reports (same location/category/time window) grouped for merge into a canonical issue.

2. Integrations (priority pillar)

• Channel connections — WhatsApp Business, Instagram, X, and the Platform channel itself. Per channel: connection status, masked credentials/tokens, webhook URL + verify token + HMAC secret, last-received timestamp, error rate / health, test-webhook action, reconnect action, and a demo/mock toggle.
• Mention inboxes — per-channel inbound content (X @mentions, Instagram mentioned_media, WhatsApp messages) with a "convert to issue" action.
• Outbound — auto-reply and status-notification templates (the closed-loop citizen updates sent over WhatsApp), quiet hours, rate caps, and delivery logs (sent / failed / retries).
• Routing rules — the category → official channel map, the keyword → category taxonomy editor, and city-detection rules.

3. Configuration (priority pillar)

• Feature flags — per-city and global toggles (events, channel badges, escalation clock, donations, etc.).
• SLA & escalation policy — the configurable SLA window (default 48h), the canonical escalation chain per category, per-step timers, business-hours and holiday calendars, auto-escalation on/off, and notification triggers.
• Scoring config — weights for ward/official/reporter 0–100 scores, grade thresholds (A–E), and refresh cadence.
• Taxonomy — categories, priorities, statuses and their allowed status transitions, flag reasons, and event types.
• App / branding per city — subdomain, name, helpline, donation/UPI details, and landing/support content.

4. Geography & Reference Data

• Cities / tenants — create and manage cities, subdomains, go-live status (live / rollout), and waitlist counts.
• Wards — ward list and metadata (constituencies, rail lines/stations), GeoJSON boundary upload (drives PostGIS-based routing), pincode ↔ ward mapping, and CSV import/export.
• Public submissions review — citizen-suggested corrections to ward/official data, in an approve/reject queue.

5. Officials & Accountability

• Offices / officials directory — offices (role × jurisdiction), contacts, verification, term dates, active/inactive status, and a name-withheld toggle (the person is stored, but public exposure is controlled). Supports CSV import/export.
• Responsibility chains — category → ordered escalation chain, with per-city overrides.
• Departments & police stations — standard CRUD (create/read/update/delete).
• Accountability scores — view computed ward/official scores, trigger recompute, apply overrides and annotations, and handle disputes.

6. Reporters

• Applications / KYC queue — review apply-to-report submissions and ID verification (PII, access-restricted), approve/reject, assign a beat, and grant the verified badge. (KYC = "know your customer," i.e. identity verification.)
• Reporter management — list, profile, stats, beat, suspend/revoke.

7. Events

Moderate NGO/community events (approve / feature / cancel / flag), track attendee counts, and manage a nominations queue — community ideas seeking organisers, which can be promoted to a full event.

8. Admins & Access (RBAC)

Admin account CRUD, roles and per-city scoping, invites, 2FA, and password policy; a roles & permissions matrix; and a citizen-user view (roles, bans, activity).

9. Notifications & Broadcast

Web-push broadcast (all cities or by-city), templates, scheduling, and delivery stats; plus platform/city announcements and banners.

10. Analytics & Reports

Dashboards covering volume, resolution, and SLA trends; ward and official leaderboards; channel performance; and reporter impact. Includes CSV/PDF exports and scheduled reports.

11. System / Ops

• Immutable audit log — every admin action (who / what / when / before → after). This is core to an accountability product.
• Queue monitor — background-job depth, failures, retries, dead-letter queue.
• Scheduled jobs — the SLA sweep and score-refresh jobs: last/next run, manual trigger.
• Integration & config-change history.
• Donations / supporters — a legacy feature (donor wall, supporter forms); include only if still wanted.

5. Screen archetypes

These archetypes are meant to be kept consistent across sections:

1. Dashboard — KPI tiles + "needs attention" cards + trend sparklines.
2. Review queue — filterable list + row-level actions + an approve/reject/edit detail drawer. Reused by: intake triage, flags, reporter applications, public submissions, events, and channel mentions.
3. Data table + CRUD — officials, wards, admins, taxonomy; with import/export.
4. Config form — flags, SLA policy, scoring weights; with save + mandatory audit note.
5. Integration card — per channel: status / health / masked credentials / test action.
6. Issue inspector drawer — accountability chain + activity log + media gallery + moderation actions.
7. Audit timeline — who/what/when with before → after diffs.
8. Analytics dashboard — charts + leaderboards + export.

6. Suggested MVP (phase 1)

The suggested minimum viable scope, as specified:

• Dashboard
• Feed Management & Review (intake + issue moderation + flags)
• Integrations (connections + mention→issue)
• Configuration (flags + SLA + taxonomy)
• Officials directory
• Reporter applications
• Admins/RBAC
• Audit log

Phase 2: analytics, events moderation, notifications/broadcast, ward-boundary (GeoJSON) upload, duplicate clustering, donations/supporters.