# arunkumar30102006/shareholder-voting-platform architecture

> Architecture diagram of the GitHub repository arunkumar30102006/shareholder-voting-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/arunkumar30102006/shareholder-voting-platform
- Repository: https://github.com/arunkumar30102006/shareholder-voting-platform

## Overview

#### Purpose and runtime
Vote India Secure is a Vite/React TypeScript single-page e-voting platform for Indian listed companies. It serves public marketing/compliance pages plus separate company-admin and shareholder voting portals. Browser entry is `src/main.tsx`; application composition and route registry are `src/App.tsx`; Vercel is the intended frontend host (`vercel.json`).

#### Frontend application shell and routing
`src/App.tsx` connects routed pages for public, company, shareholder, voting, analytics, and legal experiences. Shared navigation, SEO, error containment, and theme/UI layers are centered in:
- `src/components/layout/Navbar.tsx`
- `src/components/layout/GlobalErrorBoundary.tsx`
- `src/components/layout/SEO.tsx`

Marketing pages are distinct from authenticated workflows, providing a clear public-to-portal boundary:
- `src/pages/Index.tsx`
- `src/pages/CompanyLogin.tsx`
- `src/pages/ShareholderLogin.tsx`

#### Identity, roles, and tenant isolation
Supabase provides authentication and PostgreSQL persistence. The company-admin route guard enforces portal access before protected admin workflows:
- `src/components/auth/ProtectedAdminRoute.tsx`
- `src/integrations/supabase/client.ts`
- `supabase/migrations/20260302000000_security_advisor_fixes.sql`

Database RLS is a primary security boundary between companies, their administrators, and shareholders. Vote-specific RLS and secured summary behavior are represented by:
- `supabase/migrations/20251221125500_fix_votes_rls.sql`
- `supabase/migrations/20260225141500_secure_vote_summary.sql`

#### Company voting lifecycle
Company users register and authenticate, then manage voting events, resolutions, shareholders, and results through dedicated page-level workflows:
- `src/pages/CompanyRegister.tsx`
- `src/pages/CompanyDashboard.tsx`
- `src/pages/VotingManagement.tsx`

The data model evolves through SQL migrations for sessions, meeting dates, weighted voting, and vote aggregation:
- `supabase/migrations/20260121000000_add_meeting_dates.sql`
- `supabase/migrations/20260328000000_weighted_voting_system.sql`
- `supabase/migrations/20260224060000_fix_votes_aggregation.sql`

#### Shareholder ballot and audit flow
Shareholders log in, receive/verify OTP credentials, view their active ballot/dashboard, and submit votes through the frontend voting API. The vote path and integrity-oriented utilities are:
- `src/pages/VotingDashboard.tsx`
- `src/components/voting/VotingCard.tsx`
- `src/services/api/voting.ts`

Cryptographic/verification concepts are isolated in client libraries and supporting database optimization scripts:
- `src/lib/merkle.ts`
- `src/lib/blockchain.ts`
- `supabase/merkle_storage.sql`

Email OTP dispatch and validation occur server-side through Supabase Edge Functions, keeping provider secrets outside the browser:
- `supabase/functions/send-email-otp/index.ts`
- `supabase/functions/verify-email-otp/index.ts`
- `supabase/functions/send-shareholder-otp-email/index.ts`

#### Analytics, feedback, and AI services
Administrative and shareholder reporting use dashboard components; feedback is captured for sentiment analysis:
- `src/components/company/AdminVotingResults.tsx`
- `src/components/dashboard/VotingAnalytics.tsx`
- `src/components/ai/ShareholderFeedbackForm.tsx`

AI requests cross a browser-to-Edge-Function boundary. `ai-ops` integrates Groq/Gemini-backed summarization, chat, and sentiment capabilities; translation is separately exposed:
- `src/components/ai/DocumentSummarizer.tsx`
- `src/components/ai/VoteAssistant.tsx`
- `supabase/functions/ai-ops/index.ts`
- `supabase/functions/translate-text/index.ts`

#### External integrations and operational functions
Supabase Edge Functions are the backend execution layer (Deno), handling AI, transactional email through Resend, contact/feedback delivery, invitations, account deletion, and payment order creation. Cashfree payment UI connects to its server-side order function:
- `src/components/payment/CashfreeGateway.tsx`
- `supabase/functions/create-payment-order/index.ts`
- `supabase/functions/send-contact-message/index.ts`

Localization is client-side i18next, with translation content and a resolution-translation persistence layer:
- `src/i18n/config.ts`
- `src/i18n/locales/en.json`
- `supabase/migrations/20260304192000_create_resolution_translations.sql`

Main entry points: [`src/App.tsx`](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/App.tsx) (App routes), [`supabase/migrations/20251221125500_fix_votes_rls.sql`](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/migrations/20251221125500_fix_votes_rls.sql) (Voting records and summaries), [`src/components/auth/ProtectedAdminRoute.tsx`](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/auth/ProtectedAdminRoute.tsx) (Company portal access), [`src/pages/ShareholderLogin.tsx`](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/ShareholderLogin.tsx) (Shareholder login)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React frontend"]
  node_entry(("Browser entry<br/>Vite entry<br/>[main.tsx]"))
  node_app["App routes<br/>route registry<br/>[App.tsx]"]
  node_shell["Shared app shell<br/>navigation and safety<br/>[Navbar.tsx]"]
  node_public["Public marketing<br/>public pages<br/>[Index.tsx]"]
  node_company_auth["Company portal access<br/>admin authentication"]
  node_company_lifecycle["Company voting management<br/>admin workflow"]
  node_shareholder_auth["Shareholder login<br/>shareholder authentication"]
  node_ballot["Voting ballot<br/>shareholder workflow"]
  node_voting_api["Voting API<br/>browser data service<br/>[voting.ts]"]
  node_integrity["Vote integrity utilities<br/>Merkle and blockchain<br/>[merkle.ts]"]
  node_analytics["Results and analytics<br/>reporting UI"]
  node_ai_ui["AI and feedback UI<br/>AI client features<br/>[VoteAssistant.tsx]"]
  node_payment_ui["Cashfree payment UI<br/>payment client"]
  node_i18n["Client localization<br/>i18next<br/>[config.ts]"]
end

subgraph group_data["Supabase data boundary"]
  node_supabase_client["Supabase client<br/>browser integration<br/>[client.ts]"]
  node_auth_db[("Auth and tenant database<br/>Supabase Auth and PostgreSQL")]
  node_voting_db[("Voting records and summaries<br/>secured PostgreSQL data")]
end

subgraph group_functions["Edge Functions"]
  node_otp_functions{{"OTP functions<br/>email verification<br/>[index.ts]"}}
  node_ai_functions{{"AI operations<br/>AI Edge Function<br/>[index.ts]"}}
  node_operations{{"Operational functions<br/>Edge Function operations<br/>[index.ts]"}}
end

node_entry -->|"mounts"| node_app
node_app -->|"wraps routes"| node_shell
node_app -->|"serves"| node_public
node_app -->|"routes to"| node_company_auth
node_app -->|"routes to"| node_shareholder_auth
node_company_auth -->|"guards access to"| node_company_lifecycle
node_shareholder_auth -->|"requests verification"| node_otp_functions
node_otp_functions -->|"validates identity"| node_auth_db
node_company_auth -->|"authenticates via"| node_supabase_client
node_shareholder_auth -->|"authenticates via"| node_supabase_client
node_supabase_client -->|"uses Auth and data"| node_auth_db
node_company_lifecycle -->|"manages voting data"| node_voting_db
node_ballot -->|"submits through"| node_voting_api
node_voting_api -->|"reads and records votes"| node_voting_db
node_ballot -.->|"uses verification"| node_integrity
node_analytics -->|"reads secured summaries"| node_voting_db
node_ai_ui -->|"invokes"| node_ai_functions
node_payment_ui -->|"creates payment order"| node_operations
node_i18n -.->|"localizes"| node_app
node_ai_functions -.->|"persists feedback context"| node_voting_db

click node_entry "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/main.tsx"
click node_app "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/App.tsx"
click node_shell "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/layout/Navbar.tsx"
click node_public "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/Index.tsx"
click node_company_auth "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/auth/ProtectedAdminRoute.tsx"
click node_company_lifecycle "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/VotingManagement.tsx"
click node_shareholder_auth "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/ShareholderLogin.tsx"
click node_ballot "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/VotingDashboard.tsx"
click node_voting_api "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/services/api/voting.ts"
click node_integrity "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/lib/merkle.ts"
click node_analytics "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/company/AdminVotingResults.tsx"
click node_ai_ui "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/ai/VoteAssistant.tsx"
click node_payment_ui "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/payment/CashfreeGateway.tsx"
click node_i18n "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/i18n/config.ts"
click node_supabase_client "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/integrations/supabase/client.ts"
click node_auth_db "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/migrations/20260302000000_security_advisor_fixes.sql"
click node_voting_db "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/migrations/20251221125500_fix_votes_rls.sql"
click node_otp_functions "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/functions/verify-email-otp/index.ts"
click node_ai_functions "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/functions/ai-ops/index.ts"
click node_operations "https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/functions/create-payment-order/index.ts"

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_entry,node_app,node_shell,node_public,node_company_auth,node_company_lifecycle,node_shareholder_auth,node_ballot,node_voting_api,node_integrity,node_analytics,node_ai_ui,node_payment_ui,node_i18n toneBlue
class node_supabase_client,node_auth_db,node_voting_db toneAmber
class node_otp_functions,node_ai_functions,node_operations toneMint
```

## Components

### React frontend

Vite single-page application running in the browser.

- [Browser entry](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/main.tsx): Vite entry · `src/main.tsx`
- [App routes](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/App.tsx): route registry · Composes public, company, shareholder, voting, analytics, and legal routes. · `src/App.tsx`
- [Shared app shell](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/layout/Navbar.tsx): navigation and safety · Navigation, SEO, error containment, and UI layers. · `src/components/layout/Navbar.tsx`
- [Public marketing](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/Index.tsx): public pages · Public site boundary before portal authentication. · `src/pages/Index.tsx`
- [Company portal access](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/auth/ProtectedAdminRoute.tsx): admin authentication · Company registration, login, and protected-admin access. · `src/components/auth/ProtectedAdminRoute.tsx`
- [Company voting management](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/VotingManagement.tsx): admin workflow · Manages voting events, resolutions, shareholders, and results. · `src/pages/VotingManagement.tsx`
- [Shareholder login](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/ShareholderLogin.tsx): shareholder authentication · `src/pages/ShareholderLogin.tsx`
- [Voting ballot](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/pages/VotingDashboard.tsx): shareholder workflow · Displays active ballots and submits votes. · `src/pages/VotingDashboard.tsx`
- [Voting API](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/services/api/voting.ts): browser data service · `src/services/api/voting.ts`
- [Vote integrity utilities](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/lib/merkle.ts): Merkle and blockchain · Client-side cryptographic and verification concepts. · `src/lib/merkle.ts`
- [Results and analytics](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/company/AdminVotingResults.tsx): reporting UI · Administrative and shareholder voting reporting. · `src/components/company/AdminVotingResults.tsx`
- [AI and feedback UI](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/ai/VoteAssistant.tsx): AI client features · Summarization, vote assistance, and shareholder feedback. · `src/components/ai/VoteAssistant.tsx`
- [Cashfree payment UI](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/components/payment/CashfreeGateway.tsx): payment client · `src/components/payment/CashfreeGateway.tsx`
- [Client localization](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/i18n/config.ts): i18next · Client translation content and language configuration. · `src/i18n/config.ts`

### Supabase data boundary

Authentication, PostgreSQL, RLS, and persisted voting records.

- [Supabase client](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/src/integrations/supabase/client.ts): browser integration · Browser connection to Supabase authentication and data. · `src/integrations/supabase/client.ts`
- [Auth and tenant database](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/migrations/20260302000000_security_advisor_fixes.sql): Supabase Auth and PostgreSQL · Tenant-isolated company, administrator, and shareholder records. · `supabase/migrations/20260302000000_security_advisor_fixes.sql`
- [Voting records and summaries](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/migrations/20251221125500_fix_votes_rls.sql): secured PostgreSQL data · RLS-protected votes, weighted aggregation, sessions, and meeting data. · `supabase/migrations/20251221125500_fix_votes_rls.sql`

### Edge Functions

Deno backend operations that keep secrets off the client.

- [OTP functions](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/functions/verify-email-otp/index.ts): email verification · Server-side OTP dispatch and verification. · `supabase/functions/verify-email-otp/index.ts`
- [AI operations](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/functions/ai-ops/index.ts): AI Edge Function · Groq/Gemini summarization, chat, sentiment, and translation boundary. · `supabase/functions/ai-ops/index.ts`
- [Operational functions](https://github.com/arunkumar30102006/shareholder-voting-platform/blob/main/supabase/functions/create-payment-order/index.ts): Edge Function operations · Payment orders plus transactional contact, invitation, and account workflows. · `supabase/functions/create-payment-order/index.ts`

## Connections

- Browser entry → App routes: mounts
- App routes → Shared app shell: wraps routes
- App routes → Public marketing: serves
- App routes → Company portal access: routes to
- App routes → Shareholder login: routes to
- Company portal access → Company voting management: guards access to
- Shareholder login → OTP functions: requests verification
- OTP functions → Auth and tenant database: validates identity
- Company portal access → Supabase client: authenticates via
- Shareholder login → Supabase client: authenticates via
- Supabase client → Auth and tenant database: uses Auth and data
- Company voting management → Voting records and summaries: manages voting data
- Voting ballot → Voting API: submits through
- Voting API → Voting records and summaries: reads and records votes
- Voting ballot → Vote integrity utilities: uses verification
- Results and analytics → Voting records and summaries: reads secured summaries
- AI and feedback UI → AI operations: invokes
- Cashfree payment UI → Operational functions: creates payment order
- Client localization → App routes: localizes
- AI operations → Voting records and summaries: persists feedback context