# marubharuch/vodir architecture

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

- Interactive diagram: https://gitdiagram.com/marubharuch/vodir
- Repository: https://github.com/marubharuch/vodir

## Overview

##### Project Type and Purpose
- This is a single‐page, Progressive Web App built with React, Vite and Tailwind.
- It manages authentication and user profile entirely in the browser using React Context + localForage (IndexedDB).
- No external backend/API—offline first with persisted state.

##### File Structure
- Top‐level config files: vite.config.js, package.json, eslint.config.js.
- public/: PWA manifest.json (installable web app).
- src/
- main.jsx, index.html: app entry & shell
- src/context/: AuthContext.jsx & ProfileContext.jsx (state management)
- src/hooks/useLocalDb.js + src/localDb.js: persistence abstraction
- src/pages/: route targets (Home, Login, Registration, FamilyTree, etc.)
- src/components/: reusable UI (Navbar, Carousel, SyncButton, etc.)
- src/data/: static assets (carouselData, fa.json)
- src/housie/: game admin/user UI

##### README
- Confirms core concepts:
- AuthContext: login/logout via localForage (IndexedDB)
- ProfileContext: profile persistence
- Protected routing with PrivateRoute
- Hooks mandatory, contexts wrap App routes

##### Main Components & Boundaries
a. Browser Environment
- Service Worker / PWA Host (caching static assets)
- IndexedDB (via localForage)
b. Application Shell
- index.html + manifest.json + JS bundles served by Vite
c. React SPA
- App.jsx: root component
- React Router: route definitions & PrivateRoute
d. State Management
- AuthContext Provider
- ProfileContext Provider
- Hooks layer (useAuth, useProfile, useLocalDb)
e. UI Layer
- Pages (LoginPage, HomePage, FamilyPage, FamilyTree, Boards, RegistrationPage, HousieAdmin, HousieUser)
- Shared Components (Navbar, BottomNav, Carousel, CardList, SyncButton, InstallButton, etc.)
f. Persistence Layer
- localDb.js abstraction → localForage → IndexedDB

##### Relationships & Data Flows
- User interacts with UI Components → triggers React state updates or context actions (login, logout, updateProfile).
- Context actions call useLocalDb → localDb.js → localForage API → IndexedDB.
- React Router enforces protected routes via PrivateRoute (reads AuthContext).
- PWA “Install” uses InstallButton hooking into browser beforeinstallprompt.
- Static assets (favicon, manifest.json) served by Vite dev-server / production host.

##### Architectural Patterns & Principles
- Single‐page component hierarchy (container/pages vs. presentational/components).
- Context + custom hooks for state & side‐effect encapsulation.
- PWA caching & installability.
- Separation of concerns: UI, state, persistence.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Browser Environment
    subgraph "Browser Environment"
        SW["Service Worker & PWA Host"]:::pwa
        ReactApp["React App"]:::app
    end

    SW --> ReactApp

    %% React App Internals
    subgraph "React App"
        subgraph "App Shell"
            IndexHTML["index.html"]:::shell
            MainJS["main.jsx"]:::shell
            AppJS["App.jsx"]:::shell
            Manifest["manifest.json"]:::shell
        end

        subgraph "Router & Routes"
            Router["React Router & PrivateRoute"]:::router
        end

        subgraph "Context Providers"
            AuthCtx["AuthContext Provider"]:::state
            ProfileCtx["ProfileContext Provider"]:::state
        end

        subgraph "Hooks Layer"
            UseLocalDb["useLocalDb hook"]:::state
        end

        subgraph "UI Pages & Components"
            subgraph "Pages"
                Home["HomePage"]:::ui
                Login["LoginPage"]:::ui
                Reg["RegistrationPage"]:::ui
                Family["FamilyPage"]:::ui
                Tree["FamilyTree"]:::ui
                Boards["Boards"]:::ui
            end
            subgraph "Components"
                Nav["Navbar"]:::ui
                BotNav["BottomNav"]:::ui
                Carousel["Carousel"]:::ui
                CardList["CardList"]:::ui
                SyncBtn["SyncButton"]:::ui
                InstallBtn["InstallButton"]:::ui
                CityRibbon["CityRibbon"]:::ui
                CombinedForm["CombinedForm"]:::ui
                FamDir["FamilyDirectory"]:::ui
            end
            subgraph "Housie Game"
                HAdmin["HousieAdmin"]:::ui
                HUser["HousieUser"]:::ui
            end
        end

        %% Data Assets
        subgraph "Static Data Assets"
            CarouselData["carouselData.js"]:::data
            FAJSON["fa.json"]:::data
        end
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        LocalDb["localDb.js"]:::persist
        LocalForage["localForage API"]:::persist
        IndexedDB["IndexedDB"]:::persist
    end

    %% Connections
    ReactApp --> IndexHTML
    ReactApp --> MainJS
    ReactApp --> AppJS
    ReactApp --> Manifest

    IndexHTML --> Router
    MainJS --> Router
    AppJS --> Router

    Router --> Home
    Router --> Login
    Router --> Reg
    Router --> Family
    Router --> Tree
    Router --> Boards

    AuthCtx --> UseLocalDb
    ProfileCtx --> UseLocalDb
    UseLocalDb --> LocalDb
    LocalDb --> LocalForage
    LocalForage --> IndexedDB

    AuthCtx --> Home
    AuthCtx --> Login
    AuthCtx --> Reg
    AuthCtx --> Family
    AuthCtx --> Tree
    AuthCtx --> Boards

    ProfileCtx --> Home
    ProfileCtx --> Family
    ProfileCtx --> Tree

    Home --> Nav
    Home --> BotNav
    Home --> Carousel
    Home --> CardList
    Home --> SyncBtn
    Home --> InstallBtn

    InstallBtn --> SW

    CarouselData --> Carousel
    FAJSON --> Carousel

    HAdmin --> Nav
    HUser --> Nav

    %% Click Events
    click IndexHTML "https://github.com/marubharuch/vodir/blob/main/index.html"
    click MainJS "https://github.com/marubharuch/vodir/blob/main/src/main.jsx"
    click AppJS "https://github.com/marubharuch/vodir/blob/main/src/App.jsx"
    click Manifest "https://github.com/marubharuch/vodir/blob/main/public/manifest.json"
    click AuthCtx "https://github.com/marubharuch/vodir/blob/main/src/context/AuthContext.jsx"
    click ProfileCtx "https://github.com/marubharuch/vodir/blob/main/src/context/ProfileContext.jsx"
    click UseLocalDb "https://github.com/marubharuch/vodir/blob/main/src/hooks/useLocalDb.js"
    click LocalDb "https://github.com/marubharuch/vodir/blob/main/src/localDb.js"
    click Home "https://github.com/marubharuch/vodir/blob/main/src/pages/HomePage.jsx"
    click Login "https://github.com/marubharuch/vodir/blob/main/src/pages/LoginPage.jsx"
    click Reg "https://github.com/marubharuch/vodir/blob/main/src/pages/RegistrationPage.jsx"
    click Family "https://github.com/marubharuch/vodir/blob/main/src/pages/FamilyPage.jsx"
    click Tree "https://github.com/marubharuch/vodir/blob/main/src/pages/FamilyTree.jsx"
    click Boards "https://github.com/marubharuch/vodir/blob/main/src/pages/Boards.jsx"
    click Nav "https://github.com/marubharuch/vodir/blob/main/src/components/Navbar.jsx"
    click BotNav "https://github.com/marubharuch/vodir/blob/main/src/components/BottomNav.jsx"
    click Carousel "https://github.com/marubharuch/vodir/blob/main/src/components/Carousel.jsx"
    click CardList "https://github.com/marubharuch/vodir/blob/main/src/components/CardList.jsx"
    click SyncBtn "https://github.com/marubharuch/vodir/blob/main/src/components/SyncButton.jsx"
    click InstallBtn "https://github.com/marubharuch/vodir/blob/main/src/InstallButton.jsx"
    click CityRibbon "https://github.com/marubharuch/vodir/blob/main/src/components/CityRibbon.jsx"
    click CombinedForm "https://github.com/marubharuch/vodir/blob/main/src/components/CombinedForm.jsx"
    click FamDir "https://github.com/marubharuch/vodir/blob/main/src/components/FamilyDirectoy.jsx"
    click HAdmin "https://github.com/marubharuch/vodir/blob/main/src/housie/HousieAdmin.jsx"
    click HUser "https://github.com/marubharuch/vodir/blob/main/src/housie/HousieUser.jsx"
    click CarouselData "https://github.com/marubharuch/vodir/blob/main/src/data/carouselData.js"
    click FAJSON "https://github.com/marubharuch/vodir/blob/main/src/data/fa.json"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#009;
    classDef state fill:#DFF2E1,stroke:#28a745;
    classDef persist fill:#FFE5B4,stroke:#FF8C00;
    classDef pwa fill:#E0E0E0,stroke:#666;
    classDef shell fill:#F0F0F0,stroke:#999;
    classDef router fill:#E8F4FF,stroke:#007ACC;
    classDef data fill:#FFF5E6,stroke:#C47F00;
    class ReactApp,SW pwa
    class ReactApp app
    class MainJS,IndexHTML,AppJS,Manifest shell
    class Router router
```
