# m1amineratit/acot architecture

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

- Interactive diagram: https://gitdiagram.com/m1amineratit/acot
- Repository: https://github.com/m1amineratit/acot

## Overview

##### Project Type and Purpose
- ColdSendr is a full-stack, single-page web application (SPA) whose goal is to let users generate and manage AI-powered cold emails.
- The frontend is a React (TS) + Tailwind CSS app, and the “backend” is fully managed via Supabase (Auth, Database, Edge Functions/migrations). External AI calls go to OpenRouter’s Claude 3.5 Sonnet API.

##### File Structure
- Top-level: config files (.env, tsconfig, tailwind, vite, eslint), README, index.html.
- supabase/: database migrations defining tables (email_history, user_usage) and RLS policies.
- src/: contains the SPA code:
- components/ – UI building blocks, split into auth, features, layout, ui.
- pages/ – route targets (LandingPage, LoginPage, SignupPage, DashboardPage).
- contexts/ – AuthContext for session management.
- lib/ – Supabase client initialization.
- services/ – business logic wrappers (e.g., emailHistory CRUD).
- utils/ – generic helpers (API wrappers to OpenRouter, clipboard utilities).

##### README for Architectural Clues
- Tech stack confirms BaaS (Supabase) + client-heavy React SPA.
- Authentication flows (email/password & Google OAuth) go through Supabase Auth.
- AI generation uses an external OpenRouter endpoint.
- Database schema is managed via Supabase migrations.

##### Relationships & Data Flows
1. Browser → Hosting/CDN: fetch static assets (index.html, JS/CSS).
2. React SPA → Supabase Auth (via lib/supabase.ts): sign-up, sign-in, session token exchange.
3. React (AuthContext) holds user session; ProtectedRoute gates dashboard.
4. On “Generate Email”: React calls utils/api → OpenRouter API → returns AI content.
5. On “Save Email” or “Fetch History”: React calls services/emailHistory → Supabase Postgres.
6. Google OAuth flow: Browser → Google → callback to Supabase Auth → session back to SPA.

##### Architectural Patterns & Principles
- BaaS (Backend-as-a-Service) with Supabase handling auth, database, migrations, RLS.
- SPA component hierarchy with clear separation: UI (components), state (contexts), data layer (services), and external API wrappers (utils).
- Context API for global state; services for data access; migrations for schema evolution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Browser / Client Side"
        direction TB
        Hosting("Hosting/CDN\n(Netlify/Vercel)"):::frontend
        ReactSPA["React SPA"]:::frontend
        Hosting -->|"Fetch static assets"| ReactSPA

        subgraph "React SPA"
            direction TB
            Main("src/main.tsx"):::frontend
            App("src/App.tsx"):::frontend

            subgraph "Pages"
                direction TB
                Landing("LandingPage"):::page
                LoginPage("LoginPage"):::page
                SignupPage("SignupPage"):::page
                Dashboard("DashboardPage"):::page
            end

            subgraph "Auth Module"
                direction TB
                LoginForm("LoginForm"):::frontend
                SignupForm("SignupForm"):::frontend
                GoogleSignIn("GoogleSignInButton"):::frontend
            end

            subgraph "Feature Modules"
                direction TB
                EmailForm("EmailForm"):::frontend
                ToneAnalyzer("ToneAnalyzer"):::frontend
                EmailHistoryComp("EmailHistory"):::frontend
                EmailPreview("EmailPreview"):::frontend
                AIFollowUp("AIFollowUpSuggestions"):::frontend
            end

            subgraph "Layout Components"
                direction TB
                Header("Header"):::layout
                Footer("Footer"):::layout
                ProtectedRoute("ProtectedRoute"):::layout
            end

            AuthContext("AuthContext"):::context
            SupabaseLib("Supabase Client\n(src/lib/supabase.ts)"):::service
            EmailService("emailHistory Service"):::service
            APIUtil("OpenRouter API Client"):::util
            ClipboardUtil("Clipboard Util"):::util

            Main --> App
            App -->|renders| Landing
            App -->|routes to| LoginPage
            App -->|routes to| SignupPage
            App -->|routes to| Dashboard

            Dashboard -->|shows| EmailForm
            Dashboard -->|shows| ToneAnalyzer
            Dashboard -->|shows| EmailHistoryComp
            Dashboard -->|shows| EmailPreview
            Dashboard -->|shows| AIFollowUp

            LoginPage --> LoginForm
            SignupPage --> SignupForm

            App --> Header
            App --> Footer
            Dashboard --> ProtectedRoute

            App --> AuthContext
            AuthContext --> SupabaseLib

            EmailForm --> APIUtil
            ToneAnalyzer --> APIUtil

            EmailHistoryComp --> EmailService
            EmailPreview --> EmailService
            AIFollowUp --> EmailService
            EmailService --> SupabaseLib
        end
    end

    %% Supabase BaaS
    subgraph "Supabase Platform"
        direction TB
        Auth("Supabase Auth"):::supabase
        Postgres("Postgres DB"):::database
        Migrations("Migrations"):::migrations
        Auth --> Postgres
        Migrations --> Postgres
        ReactSPA -->|"Auth calls\n(supabase-js)"| Auth
        ReactSPA -->|"DB calls\n(supabase-js)"| Postgres
    end

    %% External Services
    subgraph "External Services"
        direction TB
        GoogleOAuth("Google OAuth"):::external
        OpenRouter("OpenRouter AI API\n(Claude 3.5 Sonnet)"):::external
        ReactSPA -->|"OAuth flow"| GoogleOAuth
        APIUtil -->|"HTTP POST"| OpenRouter
    end

    %% Migrations files click events
    click Migrations "https://github.com/m1amineratit/acot/blob/main/supabase/migrations/20250615220158_rapid_castle.sql"
    click Migrations "https://github.com/m1amineratit/acot/blob/main/supabase/migrations/20250616000636_tiny_lake.sql"
    click Migrations "https://github.com/m1amineratit/acot/blob/main/supabase/migrations/20250617104005_peaceful_temple.sql"
    click Migrations "https://github.com/m1amineratit/acot/blob/main/supabase/migrations/20250619151825_bold_valley.sql"
    click Migrations "https://github.com/m1amineratit/acot/blob/main/supabase/migrations/20250621001846_delicate_bar.sql"

    %% Click Events: Client Files
    click Main "https://github.com/m1amineratit/acot/blob/main/src/main.tsx"
    click App "https://github.com/m1amineratit/acot/blob/main/src/App.tsx"
    click LoginForm "https://github.com/m1amineratit/acot/blob/main/src/components/auth/LoginForm.tsx"
    click SignupForm "https://github.com/m1amineratit/acot/blob/main/src/components/auth/SignupForm.tsx"
    click GoogleSignIn "https://github.com/m1amineratit/acot/blob/main/src/components/auth/GoogleSignInButton.tsx"
    click EmailForm "https://github.com/m1amineratit/acot/blob/main/src/components/EmailForm.tsx"
    click AIFollowUp "https://github.com/m1amineratit/acot/blob/main/src/components/AIFollowUpSuggestions.tsx"
    click ToneAnalyzer "https://github.com/m1amineratit/acot/blob/main/src/components/features/ToneAnalyzer.tsx"
    click EmailHistoryComp "https://github.com/m1amineratit/acot/blob/main/src/components/features/EmailHistory.tsx"
    click EmailPreview "https://github.com/m1amineratit/acot/blob/main/src/components/features/EmailPreview.tsx"
    click Header "https://github.com/m1amineratit/acot/blob/main/src/components/layout/Header.tsx"
    click Footer "https://github.com/m1amineratit/acot/blob/main/src/components/Footer.tsx"
    click ProtectedRoute "https://github.com/m1amineratit/acot/blob/main/src/components/layout/ProtectedRoute.tsx"
    click Landing "https://github.com/m1amineratit/acot/blob/main/src/pages/LandingPage.tsx"
    click LoginPage "https://github.com/m1amineratit/acot/blob/main/src/pages/LoginPage.tsx"
    click SignupPage "https://github.com/m1amineratit/acot/blob/main/src/pages/SignupPage.tsx"
    click Dashboard "https://github.com/m1amineratit/acot/blob/main/src/pages/DashboardPage.tsx"
    click AuthContext "https://github.com/m1amineratit/acot/blob/main/src/contexts/AuthContext.tsx"
    click EmailService "https://github.com/m1amineratit/acot/blob/main/src/services/emailHistory.ts"
    click APIUtil "https://github.com/m1amineratit/acot/blob/main/src/utils/api.ts"
    click ClipboardUtil "https://github.com/m1amineratit/acot/blob/main/src/utils/clipboard.ts"
    click SupabaseLib "https://github.com/m1amineratit/acot/blob/main/src/lib/supabase.ts"

    %% Styles
    classDef frontend fill:#cce5ff, stroke:#0056b3
    classDef supabase fill:#d4edda, stroke:#155724
    classDef external fill:#fff3cd, stroke:#856404
    classDef database fill:#c3e6cb, stroke:#155724
    classDef migrations fill:#e2f0d9, stroke:#1b6400
    classDef service fill:#e2e3e5, stroke:#63666a
    classDef util fill:#f8d7da, stroke:#721c24
    classDef context fill:#e2e3e5, stroke:#495057
    classDef layout fill:#d1ecf1, stroke:#0c5460
    classDef page fill:#cfe2ff, stroke:#1a53ff
```
