How rohith-sp/virtualwars-c2 works
1. Overall shape
- This is a Next.js 14 App Router application with one main localized UI, a small set of API routes, and a shared library layer.
- The architecture is split cleanly into:
- Presentation in app/ and components/
- Server endpoints in app/api/*
- Shared services in lib/
- Static civic data in data/
- Localization resources in messages/
2. Primary user-facing shell
- app/layout.js owns the global HTML/body shell, global CSS, and font loading.
- app/[locale]/layout.js is the localized wrapper that loads translations and provides locale-scoped app context.
- app/[locale]/page.js is the main landing page that assembles the product sections using the reusable components.
3. Locale and language boundary
- middleware.js detects the browser language and redirects root traffic to a locale-prefixed route like /hi/ or /bn/.
- i18n.js wires up translation loading and applies a fallback-to-English merge so missing localized strings do not break the UI.
- messages/*.json are the UI translation source for 9 languages, and the locale path is the main language boundary in the system.
4. AI feature backend
- The AI-powered features are exposed through three main API routes:
- POST /api/chat
- POST /api/manifesto
- POST /api/mythbuster
- These routes all depend on lib/aiProvider.js, which centralizes model selection and failover.
- The provider chain is: Gemini primary, secondary Gemini key, then Groq/LLaMA fallback if the first keys fail or rate limit.
5. AI request flow
- The client sends a user prompt, comparison request, or claim to the corresponding API route.
- The route validates input, calls generateText or generateChat, then returns structured JSON back to the UI.
- This is the main dynamic data path in the repository and the only place where external AI services are invoked.
6. Static civic data subsystem
- Several features are backed by local JSON rather than remote services:
- data/candidates.json for candidate lookup
- data/forms.json, data/problems.json, data/facts.json, data/timeline.json
- data/flows/*.json for guided flow content in multiple languages
- These files feed UI modules like candidate search, informational cards, timeline content, and guided civic flows.
- This creates a clear boundary between static election reference data and AI-generated responses.
7. Interactive feature components
- components/ contains the visible feature modules that render the civic tools:
- chat, manifesto comparison, myth busting
- candidate search, booth locator/map
- EVM simulation, forms guidance, EPIC validation
- share card generation, timeline, ticker, and general UI helpers
- Most of these are client-side interactive components, while some are presentation wrappers around static data or AI-backed endpoints.
8. Supporting client-side services
- lib/flowEngine.js powers guided step-by-step flow interactions.
- lib/rateLimiter.js suggests API abuse control, likely for the AI endpoints.
- lib/analytics.js and components/FirebaseAnalyticsProvider.jsx indicate event tracking integration.
- lib/firebase.js plus the Firebase-related config files show there is infrastructure support for Firebase-based services or deployment integration, though Vercel is the primary production host.
9. Error containment and resilience
- app/error.js and app/global-error.js provide route-level and app-level failure boundaries.
- components/ErrorBoundary.jsx is used to isolate failures in individual sections so one broken feature does not collapse the entire civic portal.
- This is important because the app mixes many independently functioning modules, including AI calls, maps, and data-driven widgets.
10. Testing and validation boundary
- __tests__/api/* covers the API routes.
- __tests__/lib/* covers core infrastructure such as the AI provider and flow engine.
- This indicates the main test focus is on the backend behavior and shared orchestration logic, not only UI rendering.
11. Deployment and runtime
- The app is designed for Vercel deployment with environment variables supplied server-side.
- vercel.json, next.config.mjs, and the README imply standard Next.js production hosting with serverless/API route execution.
- The environment file template shows the key external dependencies are AI API keys and optional analytics configuration.
12. What to emphasize in an architecture diagram
- Draw one central localized Next.js app shell feeding many feature components.
- Show a separate API layer for chat/manifesto/mythbuster/candidate search.
- Show lib/aiProvider.js as the shared AI abstraction with failover to external model providers.
- Show data/ and messages/ as two distinct static content sources:
- civic reference data
- translated UI strings
- Put middleware in front of the app for locale routing, and error boundaries around the UI for resilience.
Main entry points: page.js Home page · layout.js Locale layout · chat/route.js Chat API · manifesto/route.js Manifesto API
Components 29
Presentation
Next.js app shell and reusable UI components
- Root layout · Defines the global HTML/body shell, fonts, and global styles.
app/layout.js - Locale layout · Loads translations and provides locale-scoped application context.
app/[locale]/layout.js - Home page · Assembles the main localized experience from reusable sections.
app/[locale]/page.js - Error boundary · Isolates failures in individual sections so the portal stays usable.
components/ErrorBoundary.jsx - Route error · Route-level failure boundary for the app router.
app/error.js - Global error · Top-level fallback for unrecoverable application failures.
app/global-error.js - Chat window · Client chat interface for prompt-driven assistance.
components/ChatWindow.jsx - Manifesto compare · Compares manifesto content and surfaces differences.
components/ManifestoCompare.jsx - Myth buster · Presents claim checking and misinformation rebuttals.
components/MythBuster.jsx - Candidate search · Searches candidates using local data and API-backed lookup.
components/CandidateSearch.jsx - Flow chat · Drives step-by-step civic flow interactions.
components/FlowChat.jsx - Language switcher · Lets the user change the active locale.
components/LanguageSwitcher.jsx
Server
API routes and request-time orchestration
- Chat API · Validates prompts and returns AI-generated chat responses.
app/api/chat/route.js - Manifesto API · Validates comparison requests and returns structured manifesto output.
app/api/manifesto/route.js - Mythbuster API · Checks claims and returns structured fact-check results.
app/api/mythbuster/route.js - Candidates API · Serves candidate lookup and search results.
app/api/candidates/route.js
Shared
Common libraries and runtime helpers
- Locale middleware · Detects browser language and redirects to a locale-prefixed route.
middleware.js - AI provider · Centralizes model selection and failover across external AI providers.
lib/aiProvider.js - Rate limiter · Controls abuse and request pressure on dynamic endpoints.
lib/rateLimiter.js - Flow engine · Runs guided multi-step flow logic for interactive civic journeys.
lib/flowEngine.js - Analytics · Collects product events and usage telemetry.
lib/analytics.js - Firebase · Provides Firebase integration support for client or deployment services.
lib/firebase.js
Content
Static civic data and localized messages
- Candidates data · Local candidate reference data used for search and lookup.
data/candidates.json - Forms data · Reference content for civic forms guidance.
data/forms.json - Problems data · Issue and problem cards used by the UI.
data/problems.json - Facts data · Short factual snippets used in ticker and info views.
data/facts.json - Timeline data · Event timeline content shown in the UI.
data/timeline.json - Flow content · Locale-specific guided flow content for multiple languages.
data/flows/flows.en.json - Translations · UI translation resources for the supported locales.
messages/en.json
Connections 30
- Locale middleware → Locale layout: redirects to · Routes root traffic into the locale-scoped app.
- Root layout → Locale layout: wraps · Provides the global shell for the localized subtree.
- Locale layout → Home page: renders · Supplies locale context to the home page.
- Locale layout → Language switcher: loads locale · Uses translation resources for active language selection.
- Home page → Chat window: includes · Main landing page assembles the chat experience.
- Home page → Manifesto compare: includes · Main landing page assembles manifesto comparison.
- Home page → Myth buster: includes · Main landing page assembles claim checking.
- Home page → Candidate search: includes · Main landing page exposes candidate lookup.
- Home page → Flow chat: includes · Main landing page exposes guided civic flows.
- Home page → Error boundary: guards · Wraps feature sections with isolated failure handling.
- Chat window → Chat API: calls · Sends prompts to the chat endpoint.
- Manifesto compare → Manifesto API: calls · Requests comparison output from the manifesto endpoint.
- Myth buster → Mythbuster API: calls · Sends claims to the mythbuster endpoint.
- Candidate search → Candidates API: queries · Fetches candidate lookup results from the API.
- Flow chat → Flow engine: drives · Uses the shared flow engine to advance steps.
- Chat API → AI provider: uses · Delegates model calls to the shared AI gateway.
- Manifesto API → AI provider: uses · Delegates model calls to the shared AI gateway.
- Mythbuster API → AI provider: uses · Delegates model calls to the shared AI gateway.
- Chat API → Rate limiter: protected by · Applies request throttling to the dynamic route.
- Manifesto API → Rate limiter: protected by · Applies request throttling to the dynamic route.
- Mythbuster API → Rate limiter: protected by · Applies request throttling to the dynamic route.
- Candidates API → Candidates data: reads · Serves results from local candidate reference data.
- Flow engine → Flow content: reads · Consumes locale-specific guided flow content.
- Locale layout → Translations: loads · Loads translated UI strings for the active locale.
- Home page → Facts data: reads · Displays static facts and ticker content.
- Home page → Timeline data: reads · Displays timeline content in the UI.
- Home page → Forms data: reads · Uses civic forms guidance content.
- Home page → Problems data: reads · Uses issue cards and problem summaries.
- Analytics → Firebase: integrates · Telemetry and Firebase support are connected in the client stack.
- Home page → Analytics: tracks · User interactions can emit product analytics.