# zapidan/newsletter-hub architecture

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

- Interactive diagram: https://gitdiagram.com/zapidan/newsletter-hub
- Repository: https://github.com/zapidan/newsletter-hub

## Overview

##### Project Type and Purpose
- This is a full-stack, cross-platform newsletter management system (“Newsletter Hub”).
- Frontend targets:
- Web (src/web, built with Vite + React + TypeScript)
- Mobile (mobile-app, built with React Native + TypeScript)
- Shared logic/components: src/common
- Backend uses Supabase: database (PostgreSQL), Auth, Edge Functions for email handling, and RLS policies via supabase/functions and supabase/migrations.
- CI/CD pipelines generate test dashboards, coverage reports, and deploy the app.

##### File Structure Analysis
- Top-level directories:
- mobile-app → React Native application for iOS/Android
- src/web → React web application
- src/common → shared hooks, services, utilities, contexts used by both front and web
- supabase → database schema (migrations) and serverless functions
- scripts → automation (test report generation, CI helpers)
- tests & src/__tests__ → unit, integration, E2E test suites (Vitest, Playwright)
- Config and deployment files: pnpm-workspace.yaml, GitHub workflows, Vite/Vitest configs, Tailwind, ESLint, tsconfig, etc.

##### Key Components
- Web Client (src/web)
- Mobile Client (mobile-app)
- Shared Library (src/common)
- Supabase Backend:
- Auth Service
- Database (Postgres) with schema migrations
- Edge Functions (handle-email)
- External Services:
- Email provider/inbound processor (invokes Edge Function)
- Hosting/CDN for Web (e.g., Vercel/Netlify/GitHub Pages)
- App Stores for Mobile
- CI/CD & Testing Infrastructure:
- GitHub Actions workflows
- Test Dashboard (static site)
- Coverage reports (html/)
- Playwright & Vitest test runners

##### Relationships & Data Flows
- User interacts with Web or Mobile → UI components → call shared API layer in src/common/services → Supabase client
- Supabase Auth for login/identity
- Queries/Mutations against Postgres via Supabase
- Real-time updates (optional) via Supabase subscriptions
- Inbound emails trigger Supabase Edge Function → processes and writes to DB
- Webhooks or scheduled tasks (if any) likewise handled by Edge Functions
- CI pipelines run tests → generate dashboards → deploy to GH Pages

##### Architectural Patterns & Principles
- Monorepo with clear separation: web, mobile, common, backend.
- Shared code drives DRY: src/common exposes contexts, hooks, services to both clients.
- Serverless functions for event-driven processing (email).
- Database migrations for schema evolution.
- Automated testing and reporting integrated into CI.

1) Users & Devices
2) Presentation Tier (Web, Mobile)
3) Application Tier (Shared Library & Supabase Edge Functions)
4) Data Tier (Postgres DB)
- “Supabase JS Client & Auth”
- “Edge Function: handle-email”
e. In Data Tier, place “Postgres (supabase/migrations)”.
- Web/Mobile → Shared Library → Supabase JS Client → Auth/DB
- Email Provider → Edge Function → DB
- CI/CD (GitHub Actions) → Test & Reporting (Test Dashboard, Coverage) → Deployment targets

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users & Devices
    subgraph "Users & Devices"
        User["User"]:::external
    end

    %% Presentation Layer
    subgraph "Presentation Layer"
        Web["Web Client\n(src/web)"]:::frontend
        Mobile["Mobile Client\n(mobile-app)"]:::frontend
    end

    %% Shared Layer
    subgraph "Shared Logic Layer"
        Common["Shared Library\n(src/common)"]:::shared
    end

    %% Application Tier
    subgraph "Application Tier"
        ClientSetup["Supabase Client Setup\nsrc/common/api/supabaseClient.ts"]:::backend
        Context["Supabase Context\nsrc/common/contexts/SupabaseContext.tsx"]:::backend
        EdgeFunc["Edge Function: handle-email\n(supabase/functions/handle-email)"]:::backend
    end

    %% Data Tier
    subgraph "Data Tier"
        Postgres["Postgres DB\n(supabase/migrations)"]:::data
    end

    %% External Services
    subgraph "External Services"
        EmailProvider["Email Provider"]:::external
        Hosting["Web Hosting/CDN"]:::external
        AppStore["App Stores"]:::external
    end

    %% CI/CD & Testing
    subgraph "CI/CD & Testing Infrastructure"
        TestWF["Test Pipeline\n.github/workflows/test.yml"]:::ci
        PagesWF["Pages Deployment\n.github/workflows/pages.yml"]:::ci
        TestDash["Test Dashboard\n(test-dashboard/index.html)"]:::ci
        Coverage["Coverage Reports\n(html/index.html)"]:::ci
        Scripts["Automation Scripts\n(scripts/)"]:::ci
    end

    %% Connections
    User --> Web
    User --> Mobile
    Web --> Common
    Mobile --> Common
    Common --> ClientSetup
    Common --> Context
    ClientSetup --> Postgres
    Context --> Postgres
    EmailProvider -->|invokes| EdgeFunc
    EdgeFunc --> Postgres
    TestWF --> TestDash
    TestWF --> Coverage
    TestWF --> Scripts
    PagesWF --> Hosting
    TestWF -->|deploy mobile| AppStore

    %% Click Events
    click Web "https://github.com/zapidan/newsletter-hub/tree/main/src/web"
    click Mobile "https://github.com/zapidan/newsletter-hub/tree/main/mobile-app"
    click Common "https://github.com/zapidan/newsletter-hub/tree/main/src/common"
    click ClientSetup "https://github.com/zapidan/newsletter-hub/blob/main/src/common/api/supabaseClient.ts"
    click Context "https://github.com/zapidan/newsletter-hub/blob/main/src/common/contexts/SupabaseContext.tsx"
    click Postgres "https://github.com/zapidan/newsletter-hub/tree/main/supabase/migrations"
    click EdgeFunc "https://github.com/zapidan/newsletter-hub/blob/main/supabase/functions/handle-email/index.ts"
    click TestWF "https://github.com/zapidan/newsletter-hub/blob/main/.github/workflows/test.yml"
    click PagesWF "https://github.com/zapidan/newsletter-hub/blob/main/.github/workflows/pages.yml"
    click TestDash "https://github.com/zapidan/newsletter-hub/blob/main/test-dashboard/index.html"
    click Coverage "https://github.com/zapidan/newsletter-hub/blob/main/html/index.html"
    click Scripts "https://github.com/zapidan/newsletter-hub/tree/main/scripts/"
    click AppStore "https://github.com/zapidan/newsletter-hub/blob/main/mobile-app/README.md"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#3498DB
    classDef shared fill:#ABEBC6,stroke:#27AE60
    classDef backend fill:#F9E79F,stroke:#D4AC0D
    classDef data fill:#F5B7B1,stroke:#C0392B
    classDef external fill:#D7DBDD,stroke:#7F8C8D
    classDef ci fill:#D2B4DE,stroke:#8E44AD
```
