# darvcodev/numeros-aleatorios architecture

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

- Interactive diagram: https://gitdiagram.com/darvcodev/numeros-aleatorios
- Repository: https://github.com/darvcodev/numeros-aleatorios

## Overview

##### Project type and purpose
- This is a single-page, client-side web application (React + Vite) whose sole purpose is to let users upload a CSV of “raffle numbers” and associated metadata, then animate a random drawing and display the winner.
- There is no backend or database; everything runs in the browser.

##### File structure
- Top-level assets:
- index.html – the SPA shell
- public/ – static files
- package.json, pnpm-lock.yaml – dependencies managed by PNPM
- vite.config.ts – build & dev-server config
- src/ contains:
- main.tsx – initializes React root
- App.tsx – holds top-level state & view switches
- components/
– Uploader.tsx (CSV import via PapaParse)
– Shuffler.tsx (animation loop using Framer Motion)
– WinnerDisplay.tsx (renders chosen entry + confetti)
- pages/Historial.tsx – (optional) history view

##### README for additional insights
- Lists core technologies: React, TypeScript, Tailwind CSS, Framer Motion, Confetti, PapaParse.
- Describes a simple user flow: upload → play → choose winner → celebrate → reset.

a. Main components
- User’s Browser (Client)
- Static File Server or CDN (serves index.html & bundled JS/CSS)
- React SPA
- Uploader Module
- Core App State Manager
- Shuffler Module
- WinnerDisplay Module
- 3rd-party Libraries:
- PapaParse (CSV parsing)
- Framer Motion (animations)
- Confetti library
- Build Tools (Vite, PNPM, TypeScript)
b. Relationships & data flow
1. User → Browser → index.html
2. index.html + bundled assets loaded by Vite dev server or static host
3. React App mounts (main.tsx → App.tsx)
4. Uploader.tsx reads CSV via PapaParse → passes array of entries to App state
5. User clicks “Play” → App routes to Shuffler.tsx
6. Shuffler animates entries; when complete → triggers random selection
7. WinnerDisplay.tsx receives chosen entry → renders UI + fires Confetti
8. “New Attempt” resets App state → returns to Uploader
c. Architectural patterns & design principles
- Component-based UI with unidirectional data flow (React hooks or context)
- Separation of concerns: parsing, animation, display are isolated in distinct components
- Static-asset serving & SPA routing (client-side only)
d. Key technologies
- React + Vite: fast dev server & bundling
- TypeScript: strong typing of CSV data & component props
- Tailwind CSS: utility-first styling of components
- PapaParse: robust CSV ingestion
- Framer Motion & Confetti: visual flair

##### Summary of elements
- Browser/Client
- Static File Server/CDN
- Build Tool (Vite) & Package Manager (PNPM)
- React SPA and its major components (Uploader, Shuffler, WinnerDisplay, App State)
- CSV parsing (PapaParse), Animations (Framer Motion), Confetti
- User interactions (“Upload CSV”, “Play”, “Choose Winner”, “Reset”)
- Data flows with clear arrowheads and labels

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Development & Build Pipeline
    subgraph "Development & Build Pipeline"
        direction TB
        PackageJSON["package.json"]:::infra
        PNPM["pnpm-lock.yaml"]:::infra
        ViteConfig["vite.config.ts"]:::infra
        TSConfig1["tsconfig.json"]:::infra
        TSConfig2["tsconfig.app.json"]:::infra
        TSConfig3["tsconfig.node.json"]:::infra
        EnvDefs["src/vite-env.d.ts"]:::infra
        GlobalStyles["src/index.css"]:::infra

        PackageJSON -->|manages deps| PNPM
        PNPM -->|configures| ViteConfig
        ViteConfig -->|uses| TSConfig1
        ViteConfig -->|uses| TSConfig2
        ViteConfig -->|uses| TSConfig3
        TSConfig1 -->|defines env| EnvDefs
        ViteConfig -->|injects styles| GlobalStyles
    end

    %% Static Hosting
    subgraph "Static Hosting"
        direction TB
        HTML["index.html"]:::infra
        Public["public/"]:::infra
        StaticHost["Static File Server / CDN"]:::infra
        HTML --> StaticHost
        Public --> StaticHost
    end

    %% Client-Side SPA
    subgraph "Client-Side SPA"
        direction TB
        Browser["User's Browser"]:::infra
        StaticHost -->|serves| Browser

        Main["src/main.tsx"]:::react
        AppShell["src/App.tsx"]:::react
        Uploader["Uploader.tsx"]:::react
        Shuffler["Shuffler.tsx"]:::react
        WinnerDisplay["WinnerDisplay.tsx"]:::react
        Historial["src/pages/Historial.tsx"]:::react

        PapaParse["PapaParse"]:::lib
        Motion["Framer Motion"]:::lib
        Confetti["Confetti"]:::lib

        CSVData["Parsed CSV Data[]"]:::data
        Selected["selectedEntry"]:::data

        Browser -->|boots SPA| HTML
        Browser -->|loads bundle| Main
        Main -->|mounts| AppShell

        AppShell -->|renders| Uploader
        Uploader -->|parses CSV| PapaParse
        PapaParse -->|outputs| CSVData
        CSVData -->|passes to| AppShell

        AppShell -->|Play event| Shuffler
        Shuffler -->|animates & selects| Selected
        Selected -->|passes to| WinnerDisplay
        WinnerDisplay -->|renders & fires| Confetti

        AppShell -->|route| Historial

        Motion --> Shuffler
        Confetti --> WinnerDisplay
    end

    %% Click Events
    click Uploader "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/components/Uploader.tsx"
    click Shuffler "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/components/Shuffler.tsx"
    click WinnerDisplay "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/components/WinnerDisplay.tsx"
    click AppShell "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/App.tsx"
    click Main "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/main.tsx"
    click HTML "https://github.com/darvcodev/numeros-aleatorios/blob/main/index.html"
    click Public "https://github.com/darvcodev/numeros-aleatorios/tree/main/public/"
    click ViteConfig "https://github.com/darvcodev/numeros-aleatorios/blob/main/vite.config.ts"
    click PackageJSON "https://github.com/darvcodev/numeros-aleatorios/blob/main/package.json"
    click GlobalStyles "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/index.css"
    click Historial "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/pages/Historial.tsx"
    click EnvDefs "https://github.com/darvcodev/numeros-aleatorios/blob/main/src/vite-env.d.ts"
    click TSConfig1 "https://github.com/darvcodev/numeros-aleatorios/blob/main/tsconfig.json"
    click TSConfig2 "https://github.com/darvcodev/numeros-aleatorios/blob/main/tsconfig.app.json"
    click TSConfig3 "https://github.com/darvcodev/numeros-aleatorios/blob/main/tsconfig.node.json"

    %% Styles
    classDef react fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef lib fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
    classDef infra fill:#D3D3D3,stroke:#000,stroke-width:1px
```
