# roberstxx/kaloris architecture

> Architecture diagram of the GitHub repository roberstxx/kaloris, 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/roberstxx/kaloris
- Repository: https://github.com/roberstxx/kaloris

## Overview

##### Project type and purpose
- This is a single‐page, full-stack web application built with React 18 + Vite + TypeScript, using Firebase (Auth + Firestore) for back-end services, Cloudinary for media storage, and localStorage as an offline cache.
- Purpose: daily nutritional tracking—users register, log meals, view dashboards, export PDF reports, and customize profiles/themes.

##### File structure
- Top-level “src/” contains subfolders:
- api/ – HTTP clients (for future back-end integrations)
- components/ – reusable UI pieces (video: FoodCard, SearchBar, etc.) + “ui/” (shadcn/ui primitives)
- context/ – React Context providers (Session, Theme, Intake)
- data/ – seed JSON for initial foods
- hooks/ – custom hooks (mobile detection, localStorage, TDEE calc)
- lib/ – external integrations & helpers (Firebase, Cloudinary, routing guards)
- pages/ – route components (Login, Register, Dashboard, Historial, Settings, Streak, NotFound, Splash)
- utils/ – pure helpers (PDF export, date, crypto, validators, stats)
- Config and scripts: Vercel, Vite, Tailwind, tsconfig, .env.example

##### README for additional insights
- Global states via Context Providers: SessionProvider, ThemeProvider, IntakeProvider
- Routing: React Router with guards (RequireAuth, RequireProfile)
- Key sequences: user registration, login, daily intake logging, PDF export
- External services: Firebase Auth/Firestore, Cloudinary, localStorage

##### Detail without over-splitting
- Essential pieces: providers, routing guards, data stores, external services
- UI components logically (shared vs. page-specific)
- Sequence for critical flows: login/onboarding, daily logging, export
- Patterns: Context API, HOC guards, offline cache sync

## Diagram (Mermaid)

```mermaid
graph TB
    Browser["Browser/Client"]:::external
    click Browser "https://github.com/roberstxx/kaloris/blob/main/src/main.tsx"

    subgraph "React Application"
        Root["App (App.tsx)"]:::reactLayer
        click Root "https://github.com/roberstxx/kaloris/blob/main/src/App.tsx"

        subgraph "Providers"
            Session["SessionProvider"]:::reactLayer
            click Session "https://github.com/roberstxx/kaloris/blob/main/src/context/SessionContext.tsx"
            Theme["ThemeProvider"]:::reactLayer
            click Theme "https://github.com/roberstxx/kaloris/blob/main/src/context/ThemeContext.tsx"
            Intake["IntakeProvider"]:::reactLayer
            click Intake "https://github.com/roberstxx/kaloris/blob/main/src/context/IntakeContext.tsx"
        end

        subgraph "Router + Guards"
            Router["Routes (Index.tsx)"]:::reactLayer
            click Router "https://github.com/roberstxx/kaloris/blob/main/src/pages/Index.tsx"
            AuthGuard["RequireAuth"]:::reactLayer
            click AuthGuard "https://github.com/roberstxx/kaloris/blob/main/src/lib/RequireAuth.tsx"
            ProfileGuard["RequireProfile"]:::reactLayer
            click ProfileGuard "https://github.com/roberstxx/kaloris/blob/main/src/lib/RequireProfile.tsx"
        end

        subgraph "Pages"
            Login["Login Page"]:::reactLayer
            click Login "https://github.com/roberstxx/kaloris/blob/main/src/pages/Login.tsx"
            Register["Register Page"]:::reactLayer
            click Register "https://github.com/roberstxx/kaloris/blob/main/src/pages/Register.tsx"
            Registro["Registro Page"]:::reactLayer
            click Registro "https://github.com/roberstxx/kaloris/blob/main/src/pages/Registro.tsx"
            Dashboard["Dashboard Page"]:::reactLayer
            click Dashboard "https://github.com/roberstxx/kaloris/blob/main/src/pages/Dashboard.tsx"
            Historial["Historial Page"]:::reactLayer
            click Historial "https://github.com/roberstxx/kaloris/blob/main/src/pages/Historial.tsx"
            Settings["Settings Page"]:::reactLayer
            click Settings "https://github.com/roberstxx/kaloris/blob/main/src/pages/Settings.tsx"
            Streak["Streak Page"]:::reactLayer
            click Streak "https://github.com/roberstxx/kaloris/blob/main/src/pages/Streak.tsx"
            Splash["Splash Loader"]:::reactLayer
            click Splash "https://github.com/roberstxx/kaloris/blob/main/src/pages/SplashLoader.tsx"
            NotFound["NotFound Page"]:::reactLayer
            click NotFound "https://github.com/roberstxx/kaloris/blob/main/src/pages/NotFound.tsx"
        end

        subgraph "Shared Components"
            FoodCard["FoodCard"]:::reactLayer
            click FoodCard "https://github.com/roberstxx/kaloris/blob/main/src/components/FoodCard.tsx"
            SearchBar["SearchBar"]:::reactLayer
            click SearchBar "https://github.com/roberstxx/kaloris/blob/main/src/components/SearchBar.tsx"
            KpiCard["KpiCard"]:::reactLayer
            click KpiCard "https://github.com/roberstxx/kaloris/blob/main/src/components/KpiCard.tsx"
            ProgressRing["ProgressRing"]:::reactLayer
            click ProgressRing "https://github.com/roberstxx/kaloris/blob/main/src/components/ProgressRing.tsx"
            StreakWidget["StreakWidget"]:::reactLayer
            click StreakWidget "https://github.com/roberstxx/kaloris/blob/main/src/components/StreakWidget.tsx"
            ThemeToggle["ThemeToggle"]:::reactLayer
            click ThemeToggle "https://github.com/roberstxx/kaloris/blob/main/src/components/ThemeToggle.tsx"
            UserAvatar["UserAvatar"]:::reactLayer
            click UserAvatar "https://github.com/roberstxx/kaloris/blob/main/src/components/UserAvatar.tsx"
            UIPrimitives["UI Primitives"]:::reactLayer
            click UIPrimitives "https://github.com/roberstxx/kaloris/tree/main/src/components/ui"
        end
    end

    subgraph "Client-side Stores & Utilities"
        LocalStorage["localStorage Cache"]:::storage
        click LocalStorage "https://github.com/roberstxx/kaloris/blob/main/src/hooks/useLocalStorage.tsx"
        PDFUtil["PDF Export (jsPDF)"]:::storage
        click PDFUtil "https://github.com/roberstxx/kaloris/blob/main/src/utils/pdf.ts"
    end

    subgraph "External Services"
        FirebaseAuth["Firebase Auth"]:::external
        click FirebaseAuth "https://github.com/roberstxx/kaloris/blob/main/src/lib/firebase.ts"
        Firestore["Firestore"]:::external
        click Firestore "https://github.com/roberstxx/kaloris/blob/main/src/lib/firebase.ts"
        Cloudinary["Cloudinary"]:::external
        click Cloudinary "https://github.com/roberstxx/kaloris/blob/main/src/lib/cloudinary.ts"
        DailyQuote["Daily Quote Utility"]:::external
        click DailyQuote "https://github.com/roberstxx/kaloris/blob/main/src/lib/dailyQuote.ts"
    end

    %% Connections
    Browser --> Root
    Root --> Session
    Root --> Theme
    Root --> Intake

    Session --> Router
    Theme --> Router
    Intake --> Router

    Router --> AuthGuard
    AuthGuard --> ProfileGuard
    ProfileGuard --> Dashboard
    AuthGuard --> Login
    AuthGuard --> Register

    Dashboard -->|Logs meal| Intake
    Intake --> LocalStorage
    Intake --> Firestore
    Firestore --> Intake

    Dashboard --> PDFUtil

    UserAvatar --> Cloudinary
    Cloudinary --> Firestore
    Firestore --> LocalStorage

    %% Styles
    classDef reactLayer fill:#D6E4FF,stroke:#4B6CB7
    classDef external fill:#DFFFE0,stroke:#2E7D32
    classDef storage fill:#FFF4D6,stroke:#E65100
```
