# NammaSeva Voice Government Service Portal A multilingual, voice-enabled citizen portal for discovering public services, submitting demo requests and complaints, tracking locally saved applications, and receiving guided assistance. ## Masterplan - Reduce language and digital-access barriers for citizens, especially elderly and rural users, through simple forms, voice input, and spoken guidance. - Support English, Tamil, Hindi, Telugu, and Malayalam across portal navigation and core UI. - Help users complete common government-service workflows: certificate requests, welfare discovery, complaint reporting, and application tracking. - Keep the current prototype privacy-conscious and low-friction: data is stored in the browser, while authentication is provided by the injected GenMB Auth SDK. - Clearly distinguish illustrative/demo tracking data from official government records. ## Tech Stack & Architecture - **Frontend:** React 18 + TypeScript, built with Vite. - **Routing:** `react-router-dom` with `HashRouter`; routes use hash URLs such as `#/services`. Do not assume server-side SPA route rewrites. - **Styling:** Tailwind CSS v4 via `@tailwindcss/vite`, with shared semantic utility classes and custom rules in `src/styles/main.css`. - **Icons:** `lucide-react`. - **Class utilities:** `clsx` and `tailwind-merge`, wrapped by `cn()` in `src/lib/utils.ts`. - **Voice:** Browser-native Web Speech recognition and Speech Synthesis APIs, used by the voice guide. Browser support is not guaranteed; preserve typed-input fallbacks. - **Authentication:** `window.genmb.auth`, injected by the script in `index.html`. `AuthProvider` wraps the SDK and exposes user/session state. - **Persistence:** Client-side browser storage through `PortalProvider`; submitted applications and complaints are prototype-local, not sent to a government backend. - **Internationalization:** Lightweight custom context in `src/i18n.tsx`, backed by flat JSON dictionaries in `src/locales/`. Provider and render order in `src/main.tsx` is intentional: ```tsx ``` `AppShell` wraps every route and owns global navigation, theme state, language access, sign-out behavior, footer, and responsive mobile navigation. There is **no Node/Express/MongoDB backend in the current codebase** and no Bhashini/Google Translate integration. Do not document or implement these as existing functionality without adding the required server/API work. ## File Structure ```text index.html # Vite entry HTML; injected GenMB Auth SDK and portal metadata/title. src/main.tsx # React bootstrap and required router/provider nesting. src/App.tsx # Hash-router route table and fallback redirect. src/i18n.tsx # Language context, localStorage persistence, flat-key t() lookup. src/locales/en.json # Complete/default English translation dictionary. src/locales/{ta,hi,te,ml}.json # Partial Tamil, Hindi, Telugu, Malayalam dictionaries; fall back to English keys. src/styles/main.css # Tailwind imports, semantic color tokens, dark mode, animations. src/providers/AuthProvider.tsx # GenMB auth session bridge: user/loading/available state. src/providers/PortalProvider.tsx # Browser-local portal records and request/complaint operations. src/data/services.ts # Canonical list of the four supported service types and translation keys. src/lib/utils.ts # cn(), NS- tracking-ID generation, locale-aware date formatting. src/hooks/usePageMeta.ts # Updates document title and description per page. src/components/AppShell.tsx # Persistent header/nav/theme toggle/auth controls/footer. src/components/Button.tsx # Shared accessible button variants and loading state. src/components/LanguageSelect.tsx # Five-language selector wired to LanguageProvider. src/components/Modal.tsx # Accessible modal with Escape, focus trapping, scroll lock, focus restore. src/components/ServiceCard.tsx # Localized service-selection card with ID-to-icon mapping. src/components/TextField.tsx # Labeled input with hint/error accessibility wiring. src/components/ToastProvider.tsx # Global success/error/info toast context; auto-dismisses after 5 seconds. src/pages/HomePage.tsx # Landing page, feature explanations, popular service entry points. src/pages/ServicesPage.tsx # Service selection and authenticated application submission form. src/pages/StatusPage.tsx # Tracking-ID lookup and browser-saved application list. src/pages/ComplaintPage.tsx # Authenticated public-service complaint submission workflow. src/pages/AssistantPage.tsx # Typed/voice question guidance and speech-output controls. src/pages/LoginPage.tsx # GenMB sign-in, sign-up, password, magic-link/OTP account flows. src/types/genmb.d.ts # Type declarations for injected window.genmb SDK. vite.config.ts # Vite React and Tailwind plugins. ``` ## Key Features ### Multilingual interface - Supported language codes are `en`, `ta`, `hi`, `te`, and `ml`. - The selected language persists under `nammaseva-language` in `localStorage`. - `t(key, values?)` resolves the active dictionary, then English, then returns the key itself. - Non-English locale files are currently incomplete by design; English fallback is expected. When adding UI copy, add English first and add translations where available. - Use flat translation keys such as `services.title`, not nested JSON objects. ### Service requests Supported services are defined only in `src/data/services.ts`: | ID | Service | |---|---| | `birthCertificate` | Birth certificate | | `incomeCertificate` | Income certificate | | `seniorPension` | Senior citizen pension | | `rationCard` | Ration card services | Requirements: - A user chooses a service, then provides full name, 10-digit mobile number, district, and purpose. - Form validation is client-side. - Submission requires authentication; unauthenticated users are directed toward sign-in rather than silently creating a record. - Successful submission generates an `NS-XXXXXX` tracking identifier via `makeTrackingId()`. - Records are saved locally by `PortalProvider`; they are available only in the same browser/storage context. - Processing times shown in cards are informational localized copy, not calculated deadlines. ### Application tracking - Users can manually enter a tracking ID; matching is case-insensitive. - `NS-DEMO812` is a deliberately labelled demo record and should remain distinguishable from user-created records. - The status page also displays applications saved in this browser. - Status values include `Submitted`, `Under review`, and `Approved`; render them through translation keys. - Dates must use `formatDate(value, language)` so display locale follows the selected UI language. ### Complaints - Complaint submission captures a category and free-text details. - Categories include water/sanitation, roads/streetlights, welfare service, and other public service. - Users are warned not to submit sensitive personal information. - Complaints are not an emergency channel; retain the emergency-services disclaimer. - Like applications, complaints are prototype-local records and require sign-in for account association. ### Voice guide - The assistant accepts typed questions and can use browser speech recognition where available. - Use the selected language to configure speech recognition/synthesis locale behavior. - Spoken output uses `speechSynthesis`; users must be able to access guidance without audio. - Handle unsupported recognition, microphone permission denial, recognition errors, and no-speech cases with visible feedback/toasts. Never make voice the only path to complete a task. - Guidance is deterministic portal help, not a live government decision engine or official eligibility determination. ### Authentication - The injected GenMB SDK provides Google sign-in, magic links, password sign-in, OTP sign-up, password reset, and sign-out. - `AuthProvider` waits for `auth.ready()` before resolving loading state and subscribes through `onAuthStateChange`. - Check `available` before relying on `window.genmb.auth`; preview/development environments may lack the SDK. - Do not store passwords, auth tokens, or GenMB user data in `PortalProvider`. - Sign-out in `AppShell` redirects to `/` and shows a toast. ## Design Guidelines - **Tone:** Calm, official-but-approachable, plain-language public-service interface. - **Layout:** Centered `max-w-7xl` content areas; generous spacing; cards/forms with rounded corners and restrained shadows. - **Color system:** Use semantic Tailwind tokens (`background`, `foreground`, `primary`, `accent`, `muted`, `destructive`, `border`, `ring`) defined in `src/styles/main.css`. Do not introduce hard-coded competing palettes. - **Theme:** Light/dark mode is controlled by the `dark` class on `` and persists as `nammaseva-theme`. - **Typography:** System sans-serif styling supplied by the app stylesheet; use strong headings and readable body sizes rather than decorative typefaces. - **Responsive behavior:** Desktop navigation appears at `lg`; language selection is hidden below `md` and moved into the mobile menu; mobile menu is toggled from the header. - **Accessibility:** Maintain visible focus rings, semantic labels, error associations, at least 40px button touch targets, keyboard-operable modals, and screen-reader-only labels where visual text is omitted. ## App Flow 1. **Arrival** - `/` shows the multilingual landing experience, voice-guide CTA, service discovery, and tracking CTA. - Global language and theme preferences can be changed from the header. 2. **Requesting a service** - User opens `/services`, selects one of the cards, and completes the request form. - If not authenticated, the portal prompts navigation to `/login`. - On submission, a local record and tracking ID are created; show a success toast/confirmation and direct the user toward tracking. 3. **Tracking** - User opens `/status` and enters a tracking ID. - Lookup finds the demo entry or locally stored application, ignoring ID case. - Unknown IDs show a clear not-found state; saved records remain visible for the current browser. 4. **Submitting a complaint** - User opens `/complaint`, selects a category, enters details, and submits while signed in. - Display the resulting local reference/confirmation. Do not imply delivery to an authority. 5. **Getting help** - User opens `/assistant`, types a question or starts voice input. - The app displays guidance and optionally reads it aloud. - If voice APIs are unavailable, keep text input and guidance fully usable. 6. **Authentication** - `/login` hosts all GenMB SDK account actions. - Existing sessions update the shell automatically through `AuthProvider`. - Unknown routes redirect to `/`. ## Conventions - Use TypeScript strict mode; avoid `any`. - Components are default exports and PascalCase (`ServiceCard.tsx`); hooks use `useX` camelCase. - Keep page-level composition in `src/pages/`; reusable presentational elements belong in `src/components/`. - Use `Button`, `TextField`, `Modal`, and `useToast` instead of recreating inconsistent controls. - Compose Tailwind classes with `cn()` when conditional classes are needed. - Use Lucide icons rather than custom SVG markup. - Keep service identifiers stable. `ServiceCard` has an explicit `iconMap`; adding a service requires updating both `ServiceKey`/`services` and that icon map. - Generate tracking IDs only with `makeTrackingId()` and format dates only with `formatDate()`. - Do not directly mutate portal records; use the `PortalProvider` API so persistence, demo handling, and reload behavior remain consistent. - Set page title/description with `usePageMeta()` for every new page. - Add routes in `src/App.tsx`, navigation entries in `src/components/AppShell.tsx` when appropriate, and translation keys in `src/locales/en.json`. - New user-facing copy must be passed through `t()`. Ensure English is complete; missing regional translations intentionally fall back to English. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.

VoiceGov Connect