# xkarol/pollify architecture

> Architecture diagram of the GitHub repository xkarol/pollify, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xkarol/pollify
- Repository: https://github.com/xkarol/pollify

## Overview

##### Project type and purpose
- Pollify is a full‑stack, monorepo web application for creating, sharing, and analyzing polls in real time.
- Frontend: Next.js + React + Tailwind (hosted on Vercel)
- Backend/API: Hono (Node framework) with serverless handlers (deployed on Vercel)
- Shared code & utilities living in `packages/` (config, types, UI library, validation, DB schema)

##### File structure
- Top‑level:
– `apps/` contains two runnable apps:
- `apps/web` – the Next.js frontend
- `apps/api` – the Hono‑based HTTP API
– `packages/` contains reusable modules: config, database setup, shared UI components, types, validation, ESLint/Prettier configs, etc.
– Root manifests: `turbo.json` (Turborepo orchestration), `docker‑compose.yml` (local Postgres & Redis), GitHub Actions workflows

##### README for insights
- The README calls out: social login (OAuth), reCAPTCHA & IP protection, real‑time analytics (Tinybird + Vercel Analytics), Stripe payments, live poll updates, CSV/JSON exports.
- Tech stack badges confirm Next.js, Hono, Turborepo, Drizzle (ORM), Zod (validation), React Query, Tailwind, Stripe, Vercel, etc.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend" 
        direction TB
        WebApp["Next.js React App"]:::frontend
        QueryClient["React Query Client"]:::frontend
        UIlib["ShadcnUI/Tailwind Components"]:::frontend
        NextAuthAPI["NextAuth OAuth API Route"]:::frontend
        AuthProvider["Auth Hooks & Provider"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        Entry["Serverless Entry Point"]:::api
        Routes["Hono HTTP Handlers"]:::api
        Middlewares["Middleware Suite"]:::api
        Services["Business Services"]:::api
        Libs["Internal Libraries"]:::api
        ConfigAPI["Core Configuration"]:::api
    end

    subgraph "Services"
        PollsService["Polls Service"]:::api
        PaymentsService["Payments Service"]:::api
        AnalyticsService["Analytics Service"]:::api
        RecaptchaService["reCAPTCHA Service"]:::api
        QRService["QR Code Service"]:::api
    end

    subgraph "Libs"
        RedisLib["Redis Caching Library"]:::api
        StripeLib["Stripe SDK Wrapper"]:::api
        TinybirdLib["Tinybird Client Wrapper"]:::api
        GeoIPLib["GeoIP Utility"]:::api
    end

    %% Data Layer
    subgraph "Data Stores"
        direction TB
        Postgres[(Postgres Database)]:::data
        Redis[(Redis Cache)]:::data
    end

    %% Shared Packages
    subgraph "Shared Packages"
        direction TB
        Config["Shared Config"]:::shared
        DB["Drizzle ORM Database Layer"]:::shared
        Types["Shared TypeScript Types"]:::shared
        Validation["Validation Schemas"]:::shared
        UIcomponents["Design System Components"]:::shared
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OAuth["OAuth Providers"]:::external
        RecaptchaExt["reCAPTCHA v3"]:::external
        StripeExt["Stripe"]:::external
        TinybirdExt["Tinybird / Vercel Analytics"]:::external
        QRGen["QR Code Generator"]:::external
    end

    %% CI/CD & Infra
    subgraph "CI/CD & Infra"
        direction TB
        GHWorkflows["GitHub Actions"]:::infra
        Vercel["Vercel Deployments"]:::infra
        DockerCompose["Docker Compose"]:::infra
    end

    %% Connections: Frontend to Shared
    WebApp -->|imports| Config
    WebApp -->|imports| UIcomponents
    WebApp -->|imports| Types
    WebApp -->|uses| QueryClient
    WebApp -->|uses UI| UIlib
    QueryClient -->|configured by| Config

    NextAuthAPI -->|provides| AuthProvider
    AuthProvider -->|wraps| WebApp

    %% Frontend to API
    WebApp -->|REST Calls| Routes

    %% API internal flow
    Entry --> Routes
    Routes --> Middlewares
    Middlewares --> Services
    Services -->|reads/writes| Postgres
    Services -->|reads/writes| Redis
    Services -->|calls| Libs
    ConfigAPI --> Entry

    %% Services to external
    PaymentsService -->|SDK| StripeExt
    RecaptchaService -->|HTTP| RecaptchaExt
    AnalyticsService -->|ingest| TinybirdExt
    QRService -->|generate| QRGen

    %% Libraries usage
    RedisLib --> Redis
    StripeLib --> StripeExt
    TinybirdLib --> TinybirdExt
    GeoIPLib -->|lookup| Routes

    %% Shared packages imported by API
    ConfigAPI --> Config
    Routes --> Types
    Routes --> Validation
    Services --> Validation
    Services --> Types
    Services --> Config
    Services --> DB

    %% Deployments
    GHWorkflows -->|deploy| Vercel
    DockerCompose --> Postgres
    DockerCompose --> Redis

    %% Click Events
    click WebApp "https://github.com/xkarol/pollify/tree/main/apps/web"
    click QueryClient "https://github.com/xkarol/pollify/blob/main/apps/web/config/query-client.ts"
    click UIlib "https://github.com/xkarol/pollify/tree/main/packages/ui"
    click NextAuthAPI "https://github.com/xkarol/pollify/blob/main/apps/web/pages/api/auth/[...nextauth].ts"
    click AuthProvider "https://github.com/xkarol/pollify/blob/main/apps/web/features/auth/components/auth-provider.tsx"
    click Routes "https://github.com/xkarol/pollify/tree/main/apps/api/src/routes"
    click Middlewares "https://github.com/xkarol/pollify/tree/main/apps/api/src/middlewares"
    click PollsService "https://github.com/xkarol/pollify/blob/main/apps/api/src/services/polls.ts"
    click PaymentsService "https://github.com/xkarol/pollify/blob/main/apps/api/src/services/payments.ts"
    click AnalyticsService "https://github.com/xkarol/pollify/blob/main/apps/api/src/services/analytics.ts"
    click RecaptchaService "https://github.com/xkarol/pollify/blob/main/apps/api/src/services/recaptcha.ts"
    click QRService "https://github.com/xkarol/pollify/blob/main/apps/api/src/services/qr.ts"
    click RedisLib "https://github.com/xkarol/pollify/blob/main/apps/api/src/lib/redis.ts"
    click StripeLib "https://github.com/xkarol/pollify/blob/main/apps/api/src/lib/stripe.ts"
    click TinybirdLib "https://github.com/xkarol/pollify/blob/main/apps/api/src/lib/tinybird.ts"
    click GeoIPLib "https://github.com/xkarol/pollify/blob/main/apps/api/src/lib/geoip.ts"
    click ConfigAPI "https://github.com/xkarol/pollify/tree/main/apps/api/src/config"
    click Entry "https://github.com/xkarol/pollify/blob/main/apps/api/src/index.ts"
    click DB "https://github.com/xkarol/pollify/tree/main/packages/db"
    click Config "https://github.com/xkarol/pollify/tree/main/packages/config"
    click Types "https://github.com/xkarol/pollify/tree/main/packages/types"
    click Validation "https://github.com/xkarol/pollify/tree/main/packages/validation"
    click UIcomponents "https://github.com/xkarol/pollify/tree/main/packages/ui/components"
    click GHWorkflows "https://github.com/xkarol/pollify/tree/main/.github/workflows"
    click DockerCompose "https://github.com/xkarol/pollify/blob/main/docker-compose.yml"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0284C7,stroke-width:1px
    classDef api fill:#D1FAE5,stroke:#048047,stroke-width:1px
    classDef data fill:#FFE4B5,stroke:#C47B00,stroke-width:1px
    classDef shared fill:#E5E7EB,stroke:#6B7280,stroke-width:1px
    classDef external fill:#F3E8FF,stroke:#7E22CE,stroke-width:1px
    classDef infra fill:#FEE2E2,stroke:#B91C1C,stroke-width:1px
```
