# midday-ai/midday architecture

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

- Interactive diagram: https://gitdiagram.com/midday-ai/midday
- Repository: https://github.com/midday-ai/midday

## Overview

##### Main Components
- Frontend Applications:
– Dashboard (a Next.js React app with a heavy UI focus using shadcn, TailwindCSS, and a rich set of React components)
– Website (public-facing Next.js site with marketing and content functionality)
– Mobile (built using Expo + ToDesktop integration)
- Backend Services:
– API (handles environment variables, Supabase functions, and custom endpoints)
– Engine (deals with provider integrations, routing for bank connections, messaging, and transformations)
- Shared Packages/Libraries:
– App-store, Documents, Email, Events, Import, Inbox, Invoice, Kv, Location, Notification, Supabase, UI, and Utils.
These components serve as the foundational libraries and business logic shared across apps.
- Infrastructure and External Services:
– Database & Storage: Supabase (database, storage, realtime, auth)
– Deployment & Edge: Vercel (edge-config and metrics)
– Cache & Messaging: Upstash (redis)
– Background Jobs: Trigger.dev
– Email and Notifications: Resend, Novu
– Bank Connection Providers: GoCardLess, Plaid, Teller
– Other Integrations: OpenPanel (events/analytics), Dub (short URLs), Polar (payment processing), Typesense (search)
- CI/CD and DevOps:
– GitHub Actions for various deployment pipelines and workflows (seen in the workflows folder).

##### Relationships and Interactions
- Frontend-to-Backend Communication:
– The Dashboard, Website, and Mobile apps interact with the API endpoints as well as the Engine. APIs might also handle authentication which connects with Supabase.
- Package and Shared Library Usage:
– Common libraries (from packages folder) are imported by multiple apps to handle functionalities like invoicing, document processing, and notifications.
– The Engine leverages provider-specific packages (for GoCardless, Plaid, Teller, etc.) to perform bank connection tasks.
- External Service Integration:
– Database operations and storage are managed via Supabase.
– External APIs and integrations connect via API connectors residing in the Engine and shared packages (e.g., for financial calculations, bank feeds).
- CI/CD Integration:
– GitHub Actions pipelines ensure that pushes, previews, and production deployments are handled consistently across different apps in the monorepo.
- Communication between Microcomponents:
– Trigger.dev runs background jobs (such as importing transactions, synchronizing bank feeds) that communicate with the API and Dashboard.
– Use of shared packages ensures modularity: for example, the UI package provides consistent components across all React apps.

##### Architectural Patterns and Design Principles
- Monorepo Structure:
– Clear separation by creating dedicated folders for apps and packages, promoting code sharing and reusability.
- Frontend-Backend Separation:
– Multiple frontend applications are clearly separated from backend services, but communicate through clearly defined APIs.
- Provider Abstraction:
– The Engine and its provider subdirectories (enablebanking, gocardless, plaid, teller) abstract away integration logic, making it easier to manage multiple bank connection types.
- Modular and Reusable Components:
– Extensive use of a shared UI library and other utility packages helps reduce duplication.
- Dependency Injection & Configuration Files:

- Partition into layers or sections:
– A Top Layer for Frontend Applications, a Middle Layer for Business Logic / Backend Services (API and Engine), and a Bottom Layer for Data & External Integrations.
- CI/CD and Development Tools as auxiliary components interacting with the codebase and deployment pipelines.
- Out specific flows (e.g., how a bank connection request flows from the Dashboard to the API and then to the appropriate provider module in the Engine).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Applications
    subgraph "Frontend Applications"
        Dashboard["Dashboard"]:::frontend
        Website["Website"]:::frontend
        Mobile["Mobile"]:::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        API["API"]:::backend
        Engine["Engine"]:::backend
    end

    %% Shared Packages / Libraries
    subgraph "Shared Packages"
        AppStore["App-store"]:::package
        Documents["Documents"]:::package
        Email["Email"]:::package
        Events["Events"]:::package
        Import["Import"]:::package
        Inbox["Inbox"]:::package
        Invoice["Invoice"]:::package
        Kv["Kv"]:::package
        Location["Location"]:::package
        Notification["Notification"]:::package
        SupabasePkg["Supabase"]:::package
        UI["UI"]:::package
        Utils["Utils"]:::package
    end

    %% External Services & Infrastructure
    subgraph "External Services & Infrastructure"
        SupabaseDB["Supabase (DB & Storage)"]:::external
        Vercel["Vercel"]:::external
        Upstash["Upstash (Redis)"]:::external
        TriggerDev["Trigger.dev"]:::external
        Resend["Resend"]:::external
        Novu["Novu"]:::external
        GoCardLess["GoCardLess"]:::external
        Plaid["Plaid"]:::external
        Teller["Teller"]:::external
        OpenPanel["OpenPanel"]:::external
        Dub["Dub"]:::external
        Polar["Polar"]:::external
        Typesense["Typesense"]:::external
    end

    %% CI/CD & DevOps
    subgraph "CI/CD & DevOps"
        GitHubActions["GitHub Actions (CI/CD)"]:::cicd
    end

    %% Frontend to Backend Communication
    Dashboard -->|"HTTP"| API
    Dashboard -->|"HTTP"| Engine
    Website   -->|"HTTP"| API
    Website   -->|"HTTP"| Engine
    Mobile    -->|"HTTP"| API
    Mobile    -->|"HTTP"| Engine

    %% Backend Services interacting with External Systems
    API -->|"Auth/DB"| SupabaseDB
    API -->|"Caching"| Upstash
    API -->|"Integrates"| Resend
    API -->|"Integrates"| Novu
    API -->|"Integrates"| OpenPanel
    API -->|"Integrates"| Dub
    API -->|"Integrates"| Polar
    API -->|"Integrates"| Typesense
    API -->|"Deploys on"| Vercel
    Engine -->|"Provider Integration"| GoCardLess
    Engine -->|"Provider Integration"| Plaid
    Engine -->|"Provider Integration"| Teller
    Engine -->|"Deploys on"| Vercel
    API -->|"BackgroundJobs"| TriggerDev

    %% Shared Packages usage by Backend
    API ---|"uses"| AppStore
    API ---|"uses"| Documents
    API ---|"uses"| Email
    API ---|"uses"| Events
    API ---|"uses"| Import
    API ---|"uses"| Inbox
    API ---|"uses"| Invoice
    API ---|"uses"| Kv
    API ---|"uses"| Location
    API ---|"uses"| Notification
    API ---|"uses"| SupabasePkg
    API ---|"uses"| Utils
    Engine ---|"uses"| UI

    %% CI/CD triggers
    GitHubActions -->|"Deploys"| Dashboard
    GitHubActions -->|"Deploys"| Website
    GitHubActions -->|"Deploys"| Mobile
    GitHubActions -->|"Deploys"| API
    GitHubActions -->|"Deploys"| Engine

    %% Style Definitions
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef package fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef cicd fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events for Frontend Applications
    click Dashboard "https://github.com/midday-ai/midday/tree/main/apps/dashboard"
    click Website "https://github.com/midday-ai/midday/tree/main/apps/website"
    click Mobile "https://github.com/midday-ai/midday/tree/main/apps/mobile"

    %% Click Events for Backend Services
    click API "https://github.com/midday-ai/midday/tree/main/apps/api"
    click Engine "https://github.com/midday-ai/midday/tree/main/apps/engine"

    %% Click Events for Shared Packages
    click AppStore "https://github.com/midday-ai/midday/tree/main/packages/app-store"
    click Documents "https://github.com/midday-ai/midday/tree/main/packages/documents"
    click Email "https://github.com/midday-ai/midday/tree/main/packages/email"
    click Events "https://github.com/midday-ai/midday/tree/main/packages/events"
    click Import "https://github.com/midday-ai/midday/tree/main/packages/import"
    click Inbox "https://github.com/midday-ai/midday/tree/main/packages/inbox"
    click Invoice "https://github.com/midday-ai/midday/tree/main/packages/invoice"
    click Kv "https://github.com/midday-ai/midday/tree/main/packages/kv"
    click Location "https://github.com/midday-ai/midday/tree/main/packages/location"
    click Notification "https://github.com/midday-ai/midday/tree/main/packages/notification"
    click SupabasePkg "https://github.com/midday-ai/midday/tree/main/packages/supabase"
    click UI "https://github.com/midday-ai/midday/tree/main/packages/ui"
    click Utils "https://github.com/midday-ai/midday/tree/main/packages/utils"

    %% Click Event for CI/CD
    click GitHubActions "https://github.com/midday-ai/midday/tree/main/.github/workflows"
```
