Feature: Bang Jaga AI — Legal & Policy Assistant

File naming: feat-bang-jaga.md

---

1. Overview

Bang Jaga as Feature vs. Persona:

• Bang Jaga (Feature): The structured chat interface at /chat. Authenticated only.
• Bang Jaga (Persona): The AI's name and avatar used across the whole app (e.g., Watchdog Commentary on The Talk Ledger). Both share the same Gemini model with distinct system prompts per context.

---

2. Functional Requirements

2.1 User Stories / Use Cases

2.2 Acceptance Criteria

• AC-01: Chat loads with an empty-state greeting, 3 template chips, and privacy notice.
• AC-02: User can send text messages and receive replies citing Perda/UU via RAG.
• AC-03: (Deferred to backlog) "Search Laws (RAG)" chip returns a structured list of regulation citations, not a paragraph. MVP: RAG context is embedded in chat responses with inline citations.
• AC-04: User can upload up to 5 images (JPG/PNG/WEBP, max 5MB each, 20MB total); images are used as multimodal context.
• AC-05: Document Preview panel activates only when the AI detects the user has both expressed intention and agreement to create a Surat Pengaduan. Preview content is driven by structured complaint data (subject, recipient, location, violation, legal basis) extracted from the AI response — not hardcoded. A "LIVE UPDATE" badge appears when a draft is active.
• AC-06: "Download PDF" sends the same structured complaint data to POST /api/export-pdf, ensuring preview and PDF use the same complaint data. Minor template/layout differences may exist between preview and PDF render.
• AC-07: "Quick-Copy WA" copies a WhatsApp-formatted version to clipboard and shows confirmation toast: "Berhasil disalin!" Falls back to wa.me link on clipboard failure.
• AC-08: "Share to Map" launches a 7-step flow: GPS request → location preview → summary edit → privacy consent → confirmation.
• AC-09: (Deferred to backlog) RAG Legal Context edit (✏️) opens a law-search modal; user-correction is logged as feedback. MVP: Users can report inaccurate responses via a per-message free-text correction, logged to rag_feedback with message_id and content.
• AC-10: Sessions are persisted per user; sidebar lists sessions grouped by TODAY / PREVIOUS 7 DAYS / older months.
• AC-11: Session title is AI-generated from the first user message (max 40 chars); fallback to "Chat – [date]".

2.3 Business Rules

• BR-01: Feature is authenticated only. Guests are redirected to the auth bottom-sheet.
• BR-02: Max 5 images per session. Accepted: JPG, PNG, WEBP. Max 5MB per image, 20MB total per session.
• BR-03: Surat Pengaduan must include: complainant identity, date, subject, factual description, applicable regulation references, and action sought.
• BR-04: RAG must not invent regulation text. If no match found, Bang Jaga states this and suggests general steps.
• BR-05: MVP: Assistant response is fetched as a complete response from Gemini and displayed with a client-side typewriter animation. True SSE streaming and debounced document generation are deferred to backlog.
• BR-06: (Deferred to backlog) The "Search Laws (RAG)" chip scopes the query to laws only. MVP: RAG context is included in every chat response inline.
• BR-07: Sessions are retained for 12 months. Users notified 30 days before deletion of inactive sessions.
• BR-08: A disclaimer is shown in every session: "Bang Jaga is not a lawyer. Always verify legal advice independently."
• BR-09: Location is required to Share to Map. If location permission is denied, the Share-to-Map flow is cancelled.

2.4 Feature Dependencies

---

3. Non-Functional Requirements

3.1 Performance

• Latency: First reply < 4s (p95) for simple queries; streamed doc preview starts within 1s of trigger.
• Throughput: Rate-limit per session/IP to cap Gemini cost and prevent abuse.
• Data volume: RAG knowledge base: hundreds of Perda/UU documents in pgvector. Single request context within model limits.

3.2 Availability & Reliability

• Uptime: Depends on Vercel + Supabase + Gemini API. Graceful error when AI is unavailable.
• Error handling: Retry once for transient Gemini errors. Show user-friendly error and [Try again]. Do not persist broken drafts.

3.3 Security & Privacy

• Auth: Authenticated only. Anonymous access not supported.
• Data: Chat content and images may contain PII/sensitive info. Stored only for session duration. Not used for AI training. Retention: 12 months or account deletion.
• Compliance: Disclaimer on every session. PII handled per local data protection expectations.

3.4 Accessibility & UX

• A11y: WCAG 2.1 AA; min tap target 48×48dp; keyboard-navigable chat; screen-reader labels for upload.
• Localization: ID primary; legal terminology in Indonesian.
• Offline / low data: Data-Saver mode: compress image uploads; no live animations in chat. If offline, show a banner and block message send.

3.5 Scalability & Limits

• Rate limits: Per-session or per-IP limits on chat messages and PDF generation to cap costs.
• Storage: Uploaded images in Supabase Storage with 12-month session retention. RAG docs in DB + pgvector.

---

4. Technical Requirements

4.1 Architecture Context

• Layer: Frontend (Next.js App Router — chat UI, live document preview), Server Actions (chat, RAG, PDF), AI (Gemini Flash streaming), Storage.
• Entry points: /chat (new session); /chat/[sessionId] (resume session); dynamic route uses useParams() in client page to avoid Promise-based params/searchParams access errors on Next.js 16; Server Actions: sendMessage, generateSuratPengaduan, exportPdf, getQuickCopy, shareComplaintToMap.

4.2 Feature-Specific Packages & Libraries

4.3 Data Model & APIs

Entities / tables used:

• chat_sessions: id, user_id, title, region_id (optional), created_at, last_message_at
• chat_messages: id, session_id, role (user|assistant), content, attachment_urls (array), created_at
• generated_documents: id, session_id, type (surat_pengaduan), content_json, created_at
• regulations: id, region_id, type (perda|uu), title, source_url, content_text, effective_date
• regulation_embeddings: id, regulation_id, chunk_index, content_chunk, embedding (vector)
• rag_feedback: id, session_id, message_id, content (free-text correction from user), created_at. (Note: The documented law-to-law correction model (originalLawId, userSelectedLawId) is deferred. MVP records free-text corrections per message.)

Key APIs / Server Actions:

• createSession() — creates a new chat_session; returns sessionId
• sendMessage(sessionId, message, imageUrls?) — append message, call RAG + Gemini, return complete response (client renders with typewriter animation)
• searchLaws(query, regionId?) — (deferred to backlog) explicit RAG-only lookup; returns structured citation list
• getRegulationContext(query, regionId?, limit) — embed query, search pgvector, return top-k chunks. Uses user's profile region when available; falls back to all regulations if no region-specific matches found.
• generateSuratPengaduan(sessionId) — (deferred to backlog) build letter from conversation; return HTML/JSON for preview. MVP: complaint data is extracted inline from the AI response via markers.
• exportPdf(sessionId) — (deferred to backlog) server-side Puppeteer PDF render. MVP: client-side PDF generation from complaint data.
• getQuickCopy(sessionId) — return WhatsApp-optimised plain text (implemented as client-side clipboard copy)
• shareComplaintToMap(sessionId, latitude, longitude, summary) — insert into walk_o_meter_reports with complaint_id
• submitRagFeedback(sessionId, messageId, content) — log user correction as free-text feedback

External APIs / services:

• Google Gemini API: chat completion, vision (images), streaming
• Google Embedding API: regulation chunk vectorization

4.4 Configuration & Environment

• Env vars: NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, GOOGLE_GEMINI_API_KEY

---

5. Sequence Diagram (Feature & Data Flow)

5.1 User asks a policy question (RAG + streaming chat)

5.2 Live document preview streaming

5.3 Share to Walk-o-Meter Map (7-step flow)

5.4 RAG Legal Context user correction

---

6. Edge Cases & UI States

6.1 Empty States

6.2 Loading States

6.3 Error States

6.4 Permission & Auth States

6.5 Session & History States

---

7. Open Questions / Decisions

• Q1: Source and update process for regulations (Perda/UU) — manual ingest vs. automated; chunking strategy for RAG.
• Q2: Legal disclaimer text and placement (confirm with legal consultant).
• Q3: Retention for anonymous-initiated images before session is authenticated.
• Q4: Whether to support inline editing of the Surat Pengaduan in preview (MVP: preview only).

---

8. Changelog