# avhijay/secure-voting-system architecture

> Architecture diagram of the GitHub repository avhijay/secure-voting-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/avhijay/secure-voting-system
- Repository: https://github.com/avhijay/secure-voting-system

## Overview

##### Project Type and Purpose
- SecureVote is a monolithic backend service built with Spring Boot 3+, exposing REST APIs for a large-scale, concurrent election/voting system.
- It implements a clean, layered architecture (Controllers → Service → Repository → Database), plus custom DSA modules (VoteTracker, VerificationQueue) for performance and integrity.

##### File Structure
- Top-level: pom.xml, Maven wrapper, src/main/java & src/main/resources, Flyway migrations under resources/db/migration.
- Java packages under com.votingSystem.secureVote:
- rest (API endpoints / Controllers)
- service & service/implementation (business logic)
- repository (Spring Data JPA interfaces)
- entity (JPA entities)
- dto (data transfer objects)
- security (Spring Security configuration, user details, auth context)
- dsa (custom data-structure modules: VerificationQueue, VoteTracker)
- GlobalExceptionHandler handles exceptions; application.properties configures DB & security.

##### README Insights
- Emphasis on thread-safe vote casting, audit logging (@Transactional), custom exception handling, and future DSA-driven optimizations (caching, duplicate prevention, ranking).

a. Main Components
- Clients (Web/Mobile UI, other services)
- Load Balancer / API Gateway (optional)
- SecureVote Service (Spring Boot application)
- Security Layer (filters, CustomUserDetailsService, SecurityConfig)
- REST Controllers (UserController, VoteController, etc.)
- Service Layer & DSA Modules (ElectionService, VoteService + VoteTracker, VerificationService + VerificationQueue)
- Repository Layer (JPA Repositories)
- Database (RDBMS with Flyway migrations)
- Audit Logging (AuditService → AuditRepository)
b. Relationships & Data Flow
- Clients → (HTTPS) → Security Layer → Controllers → Services → Repositories → Database
- VoteService invokes VoteTracker for deduplication; VerificationService enqueues into VerificationQueue → processed asynchronously
- AuditService logs each critical action to the Audit table in the same transactional context
c. Architectural Patterns & Principles
- Layered (Controller → Service → Repository)
- Transactional boundaries at Service layer (@Transactional)
- Dependency Injection (Spring)
- Separation of Concerns (security, business logic, persistence, DTO mapping)
- Modular DSA components for specialized processing
d. Key Technologies
- Spring Boot, Spring MVC, Spring Data JPA, Hibernate
- Flyway (db migrations), Maven
- Java Concurrency (thread-safety in DSA classes)
- PostgreSQL/MySQL (or chosen RDBMS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Clients"
        direction TB
        UI["Web/Mobile UI"]:::external
        Other["Other Services"]:::external
    end
    APIGW["Load Balancer/API Gateway"]:::external

    UI -->|HTTPS| APIGW
    Other -->|HTTPS| APIGW

    subgraph "SecureVote Monolith"
        direction TB
        SDN["SecureVoteApplication"]:::service
        SECfilter["Security Layer"]:::security
        GException["GlobalExceptionHandler"]:::service

        subgraph "Controllers Layer"
            direction TB
            UC["UserController"]:::controller
            VC["VoteController"]:::controller
            EC["ElectionController"]:::controller
            CC["CandidateController"]:::controller
            PC["PartiesController"]:::controller
            VRC["VerificationController"]:::controller
            AC["AuditController"]:::controller
        end

        subgraph "Service Layer"
            direction TB
            US["UserService"]:::service
            VS["VoteService"]:::service
            ES["ElectionService"]:::service
            CS["CandidateService"]:::service
            PS["PartiesService"]:::service
            VFS["VerificationService"]:::service
            AS["AuditService"]:::service
            MES["MediaEvidenceService"]:::service
        end

        subgraph "DSA Modules"
            direction TB
            VT["VoteTracker"]:::dsa
            VQ["VerificationQueue"]:::dsa
        end

        subgraph "Repositories"
            direction TB
            UR["UserRepository"]:::repo
            VR["VoteRepository"]:::repo
            ER["ElectionRepository"]:::repo
            CR["CandidateRepository"]:::repo
            PR["PartyRepository"]:::repo
            VCR["VerificationRepository"]:::repo
            AR["AuditRepository"]:::repo
            MR["MediaEvidenceRepository"]:::repo
        end
    end

    DB["Database (RDBMS)"]:::database

    APIGW --> SDN
    SDN --> SECfilter
    SECfilter --> GException
    GException --> UC
    GException --> VC
    GException --> EC
    GException --> CC
    GException --> PC
    GException --> VRC
    GException --> AC

    UC --> US
    VC --> VS
    EC --> ES
    CC --> CS
    PC --> PS
    VRC --> VFS
    AC --> AS

    VS -->|deduplicate| VT
    VFS -->|enqueue| VQ
    VQ -.->|async process| VCR

    US --> UR
    VS --> VR
    ES --> ER
    CS --> CR
    PS --> PR
    VFS --> VCR
    AS --> AR
    MES --> MR

    UR --> DB
    VR --> DB
    ER --> DB
    CR --> DB
    PR --> DB
    VCR --> DB
    AR --> DB
    MR --> DB

    classDef external fill:#ECDCCF,stroke:#B8AFA6
    classDef security fill:#FADBD8,stroke:#E74C3C
    classDef controller fill:#D6EAF8,stroke:#3498DB
    classDef service fill:#D5F5E3,stroke:#27AE60
    classDef repo fill:#FCF3CF,stroke:#F1C40F
    classDef dsa fill:#E8DAEF,stroke:#8E44AD
    classDef database fill:#F4F6F6,stroke:#95A5A6

    click SDN "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/SecureVoteApplication.java"
    click SECfilter "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/security/SecurityConfig.java"
    click SECfilter "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/security/CustomUserDetailsService.java"
    click SECfilter "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/security/CustomUserDetails.java"
    click SECfilter "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/security/AuthContext.java"
    click UC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/UserController.java"
    click VC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/VoteController.java"
    click EC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/ElectionController.java"
    click CC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/CandidateController.java"
    click PC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/PartiesController.java"
    click VRC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/VerificationController.java"
    click AC "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/rest/AuditController.java"
    click US "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/UserService.java"
    click VS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/VoteService.java"
    click ES "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/ElectionService.java"
    click CS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/CandidateService.java"
    click PS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/PartiesService.java"
    click VFS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/VerificationService.java"
    click AS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/AuditService.java"
    click MES "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/MediaEvidenceService.java"
    click US "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/UserServiceImpl.java"
    click VS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/VoteServiceImpl.java"
    click ES "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/ElectionServiceImpl.java"
    click CS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/CandidateServiceImpl.java"
    click PS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/PartiesServiceImpl.java"
    click VFS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/VerificationServiceImpl.java"
    click AS "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/AuditServiceImpl.java"
    click MES "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/service/implementation/MediaEvidenceServiceImpl.java"
    click UR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/UserRepository.java"
    click VR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/VoteRepository.java"
    click ER "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/ElectionRepository.java"
    click CR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/CandidateRepository.java"
    click PR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/PartyRepository.java"
    click VCR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/VerificationRepository.java"
    click AR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/AuditRepository.java"
    click MR "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/repository/MediaEvidenceRepository.java"
    click VT "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/dsa/VoteTracker.java"
    click VQ "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/dsa/VerificationQueue.java"
    click GException "https://github.com/avhijay/secure-voting-system/blob/main/src/main/java/com/votingSystem/secureVote/exception/GlobalExceptionHandler.java"
    click DB "https://github.com/avhijay/secure-voting-system/blob/main/src/main/resources/db/migration/V1__create_users_table.sql"
    click DB "https://github.com/avhijay/secure-voting-system/blob/main/src/main/resources/application.properties"
```
