# rohith-sp/virtualwars-c2 architecture

> Architecture diagram of the GitHub repository rohith-sp/virtualwars-c2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rohith-sp/virtualwars-c2
- Repository: https://github.com/rohith-sp/virtualwars-c2

## Overview

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: [`app/[locale]/page.js`](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/[locale]/page.js) (Home page), [`app/[locale]/layout.js`](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/[locale]/layout.js) (Locale layout), [`app/api/chat/route.js`](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/chat/route.js) (Chat API), [`app/api/manifesto/route.js`](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/manifesto/route.js) (Manifesto API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_presentation["Presentation"]
  node_root_layout["Root layout<br/>app shell<br/>[layout.js]"]
  node_locale_layout["Locale layout<br/>localized shell<br/>[layout.js]"]
  node_locale_page["Home page<br/>landing page<br/>[page.js]"]
  node_error_boundary["Error boundary<br/>ui guard<br/>[ErrorBoundary.jsx]"]
  node_app_error["Route error<br/>next error<br/>[error.js]"]
  node_global_error["Global error<br/>next error<br/>[global-error.js]"]
  node_chat_window["Chat window<br/>ai ui<br/>[ChatWindow.jsx]"]
  node_manifesto_compare["Manifesto compare<br/>ai ui"]
  node_myth_buster["Myth buster<br/>ai ui<br/>[MythBuster.jsx]"]
  node_candidate_search["Candidate search<br/>lookup ui"]
  node_flow_chat["Flow chat<br/>guided flow<br/>[FlowChat.jsx]"]
  node_language_switcher["Language switcher<br/>locale ui"]
end

subgraph group_server["Server"]
  node_chat_api["Chat API<br/>route<br/>[route.js]"]
  node_manifesto_api["Manifesto API<br/>route<br/>[route.js]"]
  node_mythbuster_api["Mythbuster API<br/>route<br/>[route.js]"]
  node_candidates_api["Candidates API<br/>route<br/>[route.js]"]
end

subgraph group_shared["Shared"]
  node_middleware["Locale middleware<br/>i18n router<br/>[middleware.js]"]
  node_ai_provider[("AI provider<br/>model gateway<br/>[aiProvider.js]")]
  node_rate_limiter["Rate limiter<br/>guard<br/>[rateLimiter.js]"]
  node_flow_engine["Flow engine<br/>orchestration<br/>[flowEngine.js]"]
  node_analytics["Analytics<br/>tracking<br/>[analytics.js]"]
  node_firebase["Firebase<br/>infra helper<br/>[firebase.js]"]
end

subgraph group_content["Content"]
  node_candidates_data["Candidates data<br/>static json<br/>[candidates.json]"]
  node_forms_data["Forms data<br/>static json<br/>[forms.json]"]
  node_problems_data["Problems data<br/>static json<br/>[problems.json]"]
  node_facts_data["Facts data<br/>static json<br/>[facts.json]"]
  node_timeline_data["Timeline data<br/>static json<br/>[timeline.json]"]
  node_flows_data["Flow content<br/>localized json<br/>[flows.en.json]"]
  node_messages["Translations<br/>locale json<br/>[en.json]"]
end

node_middleware -->|"redirects to"| node_locale_layout
node_root_layout -->|"wraps"| node_locale_layout
node_locale_layout -->|"renders"| node_locale_page
node_locale_layout -->|"loads locale"| node_language_switcher
node_locale_page -->|"includes"| node_chat_window
node_locale_page -->|"includes"| node_manifesto_compare
node_locale_page -->|"includes"| node_myth_buster
node_locale_page -->|"includes"| node_candidate_search
node_locale_page -->|"includes"| node_flow_chat
node_locale_page -->|"guards"| node_error_boundary
node_chat_window -->|"calls"| node_chat_api
node_manifesto_compare -->|"calls"| node_manifesto_api
node_myth_buster -->|"calls"| node_mythbuster_api
node_candidate_search -->|"queries"| node_candidates_api
node_flow_chat -->|"drives"| node_flow_engine
node_chat_api -->|"uses"| node_ai_provider
node_manifesto_api -->|"uses"| node_ai_provider
node_mythbuster_api -->|"uses"| node_ai_provider
node_chat_api -->|"protected by"| node_rate_limiter
node_manifesto_api -->|"protected by"| node_rate_limiter
node_mythbuster_api -->|"protected by"| node_rate_limiter
node_candidates_api -->|"reads"| node_candidates_data
node_flow_engine -->|"reads"| node_flows_data
node_locale_layout -->|"loads"| node_messages
node_locale_page -->|"reads"| node_facts_data
node_locale_page -->|"reads"| node_timeline_data
node_locale_page -->|"reads"| node_forms_data
node_locale_page -->|"reads"| node_problems_data
node_analytics -->|"integrates"| node_firebase
node_locale_page -->|"tracks"| node_analytics

click node_middleware "https://github.com/rohith-sp/virtualwars-c2/blob/main/middleware.js"
click node_root_layout "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/layout.js"
click node_locale_layout "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/[locale]/layout.js"
click node_locale_page "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/[locale]/page.js"
click node_error_boundary "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/ErrorBoundary.jsx"
click node_app_error "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/error.js"
click node_global_error "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/global-error.js"
click node_chat_window "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/ChatWindow.jsx"
click node_manifesto_compare "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/ManifestoCompare.jsx"
click node_myth_buster "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/MythBuster.jsx"
click node_candidate_search "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/CandidateSearch.jsx"
click node_flow_chat "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/FlowChat.jsx"
click node_language_switcher "https://github.com/rohith-sp/virtualwars-c2/blob/main/components/LanguageSwitcher.jsx"
click node_chat_api "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/chat/route.js"
click node_manifesto_api "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/manifesto/route.js"
click node_mythbuster_api "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/mythbuster/route.js"
click node_candidates_api "https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/candidates/route.js"
click node_ai_provider "https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/aiProvider.js"
click node_rate_limiter "https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/rateLimiter.js"
click node_flow_engine "https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/flowEngine.js"
click node_analytics "https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/analytics.js"
click node_firebase "https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/firebase.js"
click node_candidates_data "https://github.com/rohith-sp/virtualwars-c2/blob/main/data/candidates.json"
click node_forms_data "https://github.com/rohith-sp/virtualwars-c2/blob/main/data/forms.json"
click node_problems_data "https://github.com/rohith-sp/virtualwars-c2/blob/main/data/problems.json"
click node_facts_data "https://github.com/rohith-sp/virtualwars-c2/blob/main/data/facts.json"
click node_timeline_data "https://github.com/rohith-sp/virtualwars-c2/blob/main/data/timeline.json"
click node_flows_data "https://github.com/rohith-sp/virtualwars-c2/blob/main/data/flows/flows.en.json"
click node_messages "https://github.com/rohith-sp/virtualwars-c2/blob/main/messages/en.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_layout,node_locale_layout,node_locale_page,node_error_boundary,node_app_error,node_global_error,node_chat_window,node_manifesto_compare,node_myth_buster,node_candidate_search,node_flow_chat,node_language_switcher toneBlue
class node_chat_api,node_manifesto_api,node_mythbuster_api,node_candidates_api toneAmber
class node_middleware,node_ai_provider,node_rate_limiter,node_flow_engine,node_analytics,node_firebase toneMint
class node_candidates_data,node_forms_data,node_problems_data,node_facts_data,node_timeline_data,node_flows_data,node_messages toneRose
```

## Components

### Presentation

Next.js app shell and reusable UI components

- [Root layout](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/layout.js): app shell · Defines the global HTML/body shell, fonts, and global styles. · `app/layout.js`
- [Locale layout](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/[locale]/layout.js): localized shell · Loads translations and provides locale-scoped application context. · `app/[locale]/layout.js`
- [Home page](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/[locale]/page.js): landing page · Assembles the main localized experience from reusable sections. · `app/[locale]/page.js`
- [Error boundary](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/ErrorBoundary.jsx): ui guard · Isolates failures in individual sections so the portal stays usable. · `components/ErrorBoundary.jsx`
- [Route error](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/error.js): next error · Route-level failure boundary for the app router. · `app/error.js`
- [Global error](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/global-error.js): next error · Top-level fallback for unrecoverable application failures. · `app/global-error.js`
- [Chat window](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/ChatWindow.jsx): ai ui · Client chat interface for prompt-driven assistance. · `components/ChatWindow.jsx`
- [Manifesto compare](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/ManifestoCompare.jsx): ai ui · Compares manifesto content and surfaces differences. · `components/ManifestoCompare.jsx`
- [Myth buster](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/MythBuster.jsx): ai ui · Presents claim checking and misinformation rebuttals. · `components/MythBuster.jsx`
- [Candidate search](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/CandidateSearch.jsx): lookup ui · Searches candidates using local data and API-backed lookup. · `components/CandidateSearch.jsx`
- [Flow chat](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/FlowChat.jsx): guided flow · Drives step-by-step civic flow interactions. · `components/FlowChat.jsx`
- [Language switcher](https://github.com/rohith-sp/virtualwars-c2/blob/main/components/LanguageSwitcher.jsx): locale ui · Lets the user change the active locale. · `components/LanguageSwitcher.jsx`

### Server

API routes and request-time orchestration

- [Chat API](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/chat/route.js): route · Validates prompts and returns AI-generated chat responses. · `app/api/chat/route.js`
- [Manifesto API](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/manifesto/route.js): route · Validates comparison requests and returns structured manifesto output. · `app/api/manifesto/route.js`
- [Mythbuster API](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/mythbuster/route.js): route · Checks claims and returns structured fact-check results. · `app/api/mythbuster/route.js`
- [Candidates API](https://github.com/rohith-sp/virtualwars-c2/blob/main/app/api/candidates/route.js): route · Serves candidate lookup and search results. · `app/api/candidates/route.js`

### Shared

Common libraries and runtime helpers

- [Locale middleware](https://github.com/rohith-sp/virtualwars-c2/blob/main/middleware.js): i18n router · Detects browser language and redirects to a locale-prefixed route. · `middleware.js`
- [AI provider](https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/aiProvider.js): model gateway · Centralizes model selection and failover across external AI providers. · `lib/aiProvider.js`
- [Rate limiter](https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/rateLimiter.js): guard · Controls abuse and request pressure on dynamic endpoints. · `lib/rateLimiter.js`
- [Flow engine](https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/flowEngine.js): orchestration · Runs guided multi-step flow logic for interactive civic journeys. · `lib/flowEngine.js`
- [Analytics](https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/analytics.js): tracking · Collects product events and usage telemetry. · `lib/analytics.js`
- [Firebase](https://github.com/rohith-sp/virtualwars-c2/blob/main/lib/firebase.js): infra helper · Provides Firebase integration support for client or deployment services. · `lib/firebase.js`

### Content

Static civic data and localized messages

- [Candidates data](https://github.com/rohith-sp/virtualwars-c2/blob/main/data/candidates.json): static json · Local candidate reference data used for search and lookup. · `data/candidates.json`
- [Forms data](https://github.com/rohith-sp/virtualwars-c2/blob/main/data/forms.json): static json · Reference content for civic forms guidance. · `data/forms.json`
- [Problems data](https://github.com/rohith-sp/virtualwars-c2/blob/main/data/problems.json): static json · Issue and problem cards used by the UI. · `data/problems.json`
- [Facts data](https://github.com/rohith-sp/virtualwars-c2/blob/main/data/facts.json): static json · Short factual snippets used in ticker and info views. · `data/facts.json`
- [Timeline data](https://github.com/rohith-sp/virtualwars-c2/blob/main/data/timeline.json): static json · Event timeline content shown in the UI. · `data/timeline.json`
- [Flow content](https://github.com/rohith-sp/virtualwars-c2/blob/main/data/flows/flows.en.json): localized json · Locale-specific guided flow content for multiple languages. · `data/flows/flows.en.json`
- [Translations](https://github.com/rohith-sp/virtualwars-c2/blob/main/messages/en.json): locale json · UI translation resources for the supported locales. · `messages/en.json`

## Connections

- 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.
