# areait-dev/madrem architecture

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

- Interactive diagram: https://gitdiagram.com/areait-dev/madrem
- Repository: https://github.com/areait-dev/madrem

## Overview

##### Project type and purpose
- This is a single-page application (SPA) built with React, TypeScript, Vite, Tailwind CSS.
- It uses Supabase as a backend-as-a-service for authentication, database (deadlines, user settings), and real-time notifications.
- Purpose: Manage “deadlines” (contracts, domains, services, etc.) via a dashboard, with notification sounds and user settings.

##### File structure
- Top-level:
- public/ → static assets (audio files)
- src/ → application source
- package.json, vite.config.ts → build/configuration
- eslint.config.js, tsconfig*.json → linting/TypeScript config
- Under src/:
- pages/ → high-level routes (Dashboard, Login)
- components/ → reusable UI pieces (Navbar, Footer, Modals, Cards, Filters, ProtectedRoute, ThemeToggle)
- components/deadline-modals/ → domain-specific modal forms
- hooks/ → custom React hooks wrapping Supabase client, auth, deadlines, notifications, theme, user settings
- App.tsx, main.tsx → root React app and router setup
- Pattern: Component-based architecture, React Router (ProtectedRoute), custom hooks for side-effects/data fetching, Vite for dev/build.

##### README for additional insights
- Confirms Vite + React + TypeScript template.
- No explicit backend code—uses external plugins/BaaS.
- Encourages ESLint and type-aware linting (but doesn’t affect runtime architecture).

a. Main components:
- Client (Browser)
- Vite-served React SPA
- UI Components & Pages
- Build/CI (Vite / npm scripts / ESLint)
- Static Asset Store (public/ folder → served over CDN or web server)
- External Services (Supabase)
- Supabase Auth
- Supabase Database (deadlines, user settings tables)
- Supabase Realtime / Notifications
- Developer Machine (npm, IDE, Git)
b. Relationships & interactions:
1. Developer writes code → commits to Git → CI runs lint/build → deploys static bundle.
2. Browser requests index.html → loads bundled JS/CSS.
3. React App initializes, React Router routes to Login or Dashboard.
4. On Login: useAuth hook → Supabase Auth API.
5. After auth: useDeadlines hook → Supabase DB queries (CRUD).
6. useNotifications → Supabase Realtime (listen to deadlines changes).
7. UI components render data; ThemeToggle and user settings stored via useUserSettings → Supabase or localStorage.
8. Audio assets played from client/public on events.
c. Architectural patterns/design principles:
- Component-based UI decomposition
- Custom hooks encapsulate data layer and side-effects (Dependency Inversion)
- ProtectedRoute for access control (Route Guard)
- Separation of concerns: UI vs. data layer vs. build/config
- Externalizing state to BaaS (Supabase) for zero-backend maintenance
d. Key technologies/frameworks:
- Vite (dev server, bundler)
- React + React Router
- TypeScript
- Tailwind CSS
- Supabase SDK (auth, database, realtime)
- ESLint, Prettier, commitlint for code quality

##### Details to capture (don’t overthink—split into granular pieces)
- Public assets (audio) served as static files
- Root App → Router → Pages → Components
- Hooks as the interface to Supabase services
- Environment/config (dotenv or VITE_ env vars for Supabase URL/keys)
- User flows: login/auth, fetch deadlines, create/update/delete, realtime updates, theme toggles

## Diagram (Mermaid)

```mermaid
graph TD
    %% Developer and CI/CD
    Dev["Developer Machine"]:::dev
    CI["CI/CD Pipeline"]:::ci
    ESLint["ESLint & Commitlint"]:::ci_tool
    ViteBuild["Vite Build"]:::build
    Deploy["Deploy Static Bundle"]:::ci

    Dev -->|writes code & commits| CI
    CI -->|runs lint & tests| ESLint
    ESLint -->|runs| ViteBuild
    ViteBuild -->|outputs| Deploy

    %% Client Layer
    subgraph "Client - Browser" 
        direction TB
        Request["Browser requests index.html"]:::browser
        subgraph "SPA Bundle Loaded"
            direction TB
            IndexHTML["index.html"]:::client_ui
            Main["main.tsx"]:::client_ui
            AppComp["App.tsx"]:::client_ui

            subgraph "Router & Pages"
                direction TB
                Protected["ProtectedRoute"]:::client_ui
                LoginPage["Login.tsx"]:::client_ui
                DashboardPage["Dashboard.tsx"]:::client_ui
            end

            subgraph "UI Components"
                direction TB
                Navbar["Navbar"]:::client_ui
                Footer["Footer"]:::client_ui
                Inactivity["InactivityHandler"]:::client_ui
                ThemeToggle["ThemeToggle"]:::client_ui
                ViewToggle["ViewToggle"]:::client_ui
                FilterChips["FilterChips"]:::client_ui
                FilterSidebar["FilterSidebar"]:::client_ui
                DeadlineCard["DeadlineCard"]:::client_ui
                subgraph "Deadline Modals"
                    direction TB
                    AddModal["AddDeadlineModal"]:::client_ui
                    CatModal["CategoryPickerModal"]:::client_ui
                    SettingsModal["SettingsModal"]:::client_ui
                    Abbonamenti["AbbonamentiModal"]:::client_ui
                    Contratti["ContrattiModal"]:::client_ui
                    Dominio["DominioModal"]:::client_ui
                    PowerMail["PowerMailModal"]:::client_ui
                    Social["SocialModal"]:::client_ui
                end
            end

            subgraph "Hooks (Data Access Layer)"
                direction TB
                SupabaseClient["supabaseClient"]:::hook
                AuthHook["useAuth"]:::hook
                DeadlinesHook["useDeadlines"]:::hook
                NotifHook["useNotifications"]:::hook
                SettingsHook["useUserSettings"]:::hook
                ThemeHook["useTheme"]:::hook
            end

            subgraph "Global Styles & Assets"
                direction TB
                IndexCSS["index.css"]:::client_ui
                AppCSS["App.css"]:::client_ui
                DotGrid["DotGrid.tsx"]:::client_ui
                subgraph "Static Audio Assets"
                    direction TB
                    AudioClose["close.mp3"]:::asset
                    AudioDelete["delete.mp3"]:::asset
                    AudioError["error.mp3"]:::asset
                    AudioSuccess["success.mp3"]:::asset
                    AudioUpdate["update.mp3"]:::asset
                end
            end
        end
    end

    Deploy --> Request
    Request --> IndexHTML
    IndexHTML --> Main
    Main --> AppComp

    AppComp --> Protected
    Protected -->|guards| LoginPage
    Protected -->|guards| DashboardPage

    LoginPage --> AuthHook
    AuthHook --> SupabaseAuth["Supabase Auth"]:::external
    DashboardPage --> DeadlinesHook
    DeadlinesHook --> SupabaseDB["Supabase DB"]:::external
    DashboardPage --> NotifHook
    NotifHook --> SupabaseRealtime["Supabase Realtime"]:::external
    AppComp --> SettingsHook
    SettingsHook --> SupabaseDB
    AppComp --> ThemeHook

    %% Config & Tools
    subgraph "Configuration & Tools"
        direction TB
        ViteConfig["vite.config.ts"]:::config
        TailwindConfig["tailwind.config.js"]:::config
        PostCSS["postcss.config.js"]:::config
        TSConfig["tsconfig.json / tsconfig.app.json / tsconfig.node.json / vite-env.d.ts"]:::config
        ESLintConfig["eslint.config.js / commitlintrc.js"]:::config
        PackageJSON["package.json"]:::config
        ViteConfig --> ViteBuild
        TailwindConfig --> ViteBuild
        PostCSS --> ViteBuild
        TSConfig --> ViteBuild
        ESLintConfig --> ESLint
        PackageJSON --> ViteBuild
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SupabaseAuth
        SupabaseDB
        SupabaseRealtime
    end

    %% Click Events
    click ViteConfig "https://github.com/areait-dev/madrem/blob/main/vite.config.ts"
    click TailwindConfig "https://github.com/areait-dev/madrem/blob/main/tailwind.config.js"
    click PostCSS "https://github.com/areait-dev/madrem/blob/main/postcss.config.js"
    click TSConfig "https://github.com/areait-dev/madrem/blob/main/tsconfig.json"
    click ESLintConfig "https://github.com/areait-dev/madrem/blob/main/eslint.config.js"
    click ESLintConfig "https://github.com/areait-dev/madrem/blob/main/commitlintrc.js"
    click AudioClose "https://github.com/areait-dev/madrem/blob/main/public/close.mp3"
    click AudioDelete "https://github.com/areait-dev/madrem/blob/main/public/delete.mp3"
    click AudioError "https://github.com/areait-dev/madrem/blob/main/public/error.mp3"
    click AudioSuccess "https://github.com/areait-dev/madrem/blob/main/public/success.mp3"
    click AudioUpdate "https://github.com/areait-dev/madrem/blob/main/public/update.mp3"
    click AppComp "https://github.com/areait-dev/madrem/blob/main/src/App.tsx"
    click Main "https://github.com/areait-dev/madrem/blob/main/src/main.tsx"
    click IndexHTML "https://github.com/areait-dev/madrem/blob/main/index.html"
    click IndexCSS "https://github.com/areait-dev/madrem/blob/main/src/index.css"
    click AppCSS "https://github.com/areait-dev/madrem/blob/main/src/App.css"
    click DotGrid "https://github.com/areait-dev/madrem/blob/main/src/DotGrid.tsx"
    click LoginPage "https://github.com/areait-dev/madrem/blob/main/src/pages/Login.tsx"
    click DashboardPage "https://github.com/areait-dev/madrem/blob/main/src/pages/Dashboard.tsx"
    click Protected "https://github.com/areait-dev/madrem/blob/main/src/components/ProtectedRoute.tsx"
    click Navbar "https://github.com/areait-dev/madrem/blob/main/src/components/Navbar.tsx"
    click Footer "https://github.com/areait-dev/madrem/blob/main/src/components/Footer.tsx"
    click Inactivity "https://github.com/areait-dev/madrem/blob/main/src/components/InactivityHandler.tsx"
    click ThemeToggle "https://github.com/areait-dev/madrem/blob/main/src/components/ThemeToggle.tsx"
    click ViewToggle "https://github.com/areait-dev/madrem/blob/main/src/components/ViewToggle.tsx"
    click FilterChips "https://github.com/areait-dev/madrem/blob/main/src/components/FilterChips.tsx"
    click FilterSidebar "https://github.com/areait-dev/madrem/blob/main/src/components/FilterSidebar.tsx"
    click DeadlineCard "https://github.com/areait-dev/madrem/blob/main/src/components/DeadlineCard.tsx"
    click AddModal "https://github.com/areait-dev/madrem/blob/main/src/components/AddDeadlineModal.tsx"
    click CatModal "https://github.com/areait-dev/madrem/blob/main/src/components/CategoryPickerModal.tsx"
    click SettingsModal "https://github.com/areait-dev/madrem/blob/main/src/components/SettingsModal.tsx"
    click Abbonamenti "https://github.com/areait-dev/madrem/blob/main/src/components/deadline-modals/AbbonamentiModal.tsx"
    click Contratti "https://github.com/areait-dev/madrem/blob/main/src/components/deadline-modals/ContrattiModal.tsx"
    click Dominio "https://github.com/areait-dev/madrem/blob/main/src/components/deadline-modals/DominioModal.tsx"
    click PowerMail "https://github.com/areait-dev/madrem/blob/main/src/components/deadline-modals/PowerMailModal.tsx"
    click Social "https://github.com/areait-dev/madrem/blob/main/src/components/deadline-modals/SocialModal.tsx"
    click SupabaseClient "https://github.com/areait-dev/madrem/blob/main/src/hooks/supabaseClient.ts"
    click AuthHook "https://github.com/areait-dev/madrem/blob/main/src/hooks/useAuth.tsx"
    click DeadlinesHook "https://github.com/areait-dev/madrem/blob/main/src/hooks/useDeadlines.ts"
    click NotifHook "https://github.com/areait-dev/madrem/blob/main/src/hooks/useNotifications.ts"
    click SettingsHook "https://github.com/areait-dev/madrem/blob/main/src/hooks/useUserSettings.ts"
    click ThemeHook "https://github.com/areait-dev/madrem/blob/main/src/hooks/useTheme.ts"
    click TSConfig "https://github.com/areait-dev/madrem/blob/main/tsconfig.app.json"
    click TSConfig "https://github.com/areait-dev/madrem/blob/main/tsconfig.node.json"
    click TSConfig "https://github.com/areait-dev/madrem/blob/main/vite-env.d.ts"
    click PackageJSON "https://github.com/areait-dev/madrem/blob/main/package.json"

    %% Styles
    classDef dev fill:#dddddd,stroke:#888888,stroke-width:1px
    classDef ci fill:#bbbbbb,stroke:#666666,stroke-width:1px
    classDef ci_tool fill:#aaaaaa,stroke:#555555,stroke-width:1px
    classDef build fill:#cccccc,stroke:#777777,stroke-width:1px
    classDef client_ui fill:#bbdefb,stroke:#2196f3,stroke-width:1px
    classDef hook fill:#c8e6c9,stroke:#4caf50,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#ff9800,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#9e9e9e,stroke-width:1px
    classDef asset fill:#f0f4c3,stroke:#cddc39,stroke-width:1px
    classDef browser fill:#e3f2fd,stroke:#90caf9,stroke-width:1px
```
