# ericnguyen1206/votify architecture

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

- Interactive diagram: https://gitdiagram.com/ericnguyen1206/votify
- Repository: https://github.com/ericnguyen1206/votify

## Overview

##### Main Components
- Client Layer:
- Next.js Frontend (voting-frontend) that handles user interactions such as login, registration, and submitting votes.
- API Gateway Layer:
- NGINX API Gateway (nginx.conf and infra/nginx configuration) for routing and load balancing incoming requests.
- Backend Services:
- Vote API Service in Golang (voting-service’s cmd/api directory) which accepts vote submissions and checks campaign metadata.
- Vote Aggregation Service in Golang (aggregation-service and parts of voting-service) to process vote messages from Kafka.
- Realtime Notification Service (WebSocket service from the backend code) responsible for pushing live updates to the frontend.
- Message Broker using Apache Kafka (referenced in docs and infra/kafka) for asynchronous vote processing.
- Infrastructure Services:
- MySQL database for storing votes and campaign metadata (configured in docker-compose and k8s YAML files).
- Redis for in-memory caching of aggregated vote counts.
- Additional supporting elements such as monitoring (Prometheus & Grafana as mentioned in the high-level design, though not directly visible in file tree but noted in documentation).

##### Relationships and Data Flow
- The frontend sends vote submissions and requests for real-time updates to the NGINX API gateway.
- The API gateway routes these requests to the Vote API Service.
- The Vote API Service verifies time constraints (using MySQL) and pushes valid votes to Apache Kafka.
- The Vote Aggregation Service consumes votes from Kafka, aggregates them, updates the cache in Redis, and writes final results back to MySQL.
- The Realtime Notification Service monitors Redis and pushes live updates back to the Next.js frontend.
- Optionally, monitoring tools are integrated with backend services to track performance and system health.

##### Architectural Patterns and Technologies
- Microservices Architecture: Multiple distinct services (Vote API, Vote Aggregation, Notification) interacting via asynchronous messaging (Kafka) lends itself to scalability and independent deployment.
- API Gateway and Load Balancing: NGINX sits in front, routing client requests to appropriate backend services.
- Event-driven communication: Use of Apache Kafka forms an event-driven pipeline for vote processing.
- Containerization & Orchestration: Docker, Docker Compose, and Kubernetes configuration files (k8s/) indicate that the services are containerized and deployed through orchestration mechanisms.
- Use of Golang for backend services and Next.js for the frontend ensures performance and a modern UI.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Client Layer
    subgraph "Client Layer"
        FE["Next.js Frontend"]:::frontend
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        NG["NGINX API Gateway"]:::gateway
    end

    %% Backend Services
    subgraph "Backend Services"
        API["Golang Vote API Service"]:::service
        KA["Apache Kafka (Message Broker)"]:::middleware
        AG["Golang Vote Aggregation Service"]:::service
        RT["Realtime Notification Service"]:::service
        MON["Monitoring (Prometheus & Grafana)"]:::monitoring
    end

    %% Infrastructure Services
    subgraph "Infrastructure Services"
        DB["MySQL Database"]:::database
        RC["Redis Cache"]:::cache
    end

    %% Data Flow Connections
    FE -->|"vote_submissions"| NG
    NG -->|"route_requests"| API
    API -->|"push_votes"| KA
    API -->|"metadata_check"| DB
    KA -->|"consume_votes"| AG
    AG -->|"update_cache"| RC
    AG -->|"persist_data"| DB
    RC -->|"live_updates"| RT
    RT -->|"push_notifications"| FE

    %% Monitoring connections
    API ---|"metrics"| MON
    AG ---|"metrics"| MON
    RT ---|"metrics"| MON

    %% Click Events
    click FE "https://github.com/ericnguyen1206/votify/tree/main/voting-frontend/"
    click NG "https://github.com/ericnguyen1206/votify/blob/main/nginx.conf"
    click API "https://github.com/ericnguyen1206/votify/tree/main/voting-service/cmd/api/"
    click AG "https://github.com/ericnguyen1206/votify/tree/main/aggregation-service/cmd/api/"
    click KA "https://github.com/ericnguyen1206/votify/blob/main/kafka-init.sh"
    click DB "https://github.com/ericnguyen1206/votify/blob/main/docker-compose.yml"
    click DB "https://github.com/ericnguyen1206/votify/blob/main/k8s/k8s-deployment.yml"

    %% Styles
    classDef frontend fill:#FAD,stroke:#333,stroke-width:2px;
    classDef gateway fill:#BBC,stroke:#333,stroke-width:2px;
    classDef service fill:#CFC,stroke:#333,stroke-width:2px;
    classDef middleware fill:#FCA,stroke:#333,stroke-width:2px;
    classDef database fill:#FDD,stroke:#333,stroke-width:2px;
    classDef cache fill:#CEF,stroke:#333,stroke-width:2px;
    classDef monitoring fill:#DDD,stroke:#333,stroke-width:2px;
```
