# heymustafa02/zapy architecture

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

- Interactive diagram: https://gitdiagram.com/heymustafa02/zapy
- Repository: https://github.com/heymustafa02/zapy

## Overview

##### Project Type and Purpose
- This is a full-stack, event-driven automation platform (“zapy”) where users define “zaps” (trigger → action workflows).
- Key user flows: signup/login, create/manage zaps, trigger execution (e.g. send email, interact with blockchain).
- Implementation uses:
- Frontend: Next.js + TypeScript + Tailwind
- Primary-backend: Node.js + Prisma + REST/Router for user, zap, trigger, action
- Hooks service: processes real-time trigger events (outbox pattern)
- Processor service: orchestrates zap runs and scheduling
- Worker service: performs side-effects (email, Ethereum, Solana)

##### File-Structure Analysis
- frontend/: Next.js app with pages (dashboard, login, signup, zap creation) and reusable UI components
- hooks/: Node.js microservice (Prisma + migrations) that reads outbox entries and emits hook events
- primary-backend/: Core REST API + Prisma schema + user/zap/trigger/action routers + middleware
- processor/: Lightweight orchestrator microservice managing the lifecycle of zap runs
- worker/: Background worker microservice handling external integrations (email.ts, eth.ts, solana.ts, parser.ts)
- All services use Prisma migrations for their own database schema → each may share a central database or have isolated schemas.

##### Important Architectural Patterns
- Microservices: each logical component is its own service folder
- Event-driven / Outbox Pattern: primary-backend writes triggers/actions to an outbox table; hooks or processor pick them up
- Shared Database (Prisma) vs service-specific schemas
- Background workers for side-effects and blockchain interactions
- API-driven frontend communicating via REST endpoints

##### Main Components and Interactions
a. Frontend (Next.js)
- UI pages + component library
- Calls Primary-backend via HTTP (e.g. /api/login, /api/zaps)
b. Primary-backend (API)
- Exposes user/zap/trigger/action endpoints
- Persists to central relational DB via Prisma
- Writes “outbox” records for events (new trigger, run zap)
c. Hooks Service
- Polls or subscribes to outbox table for trigger events
- Emits webhooks or internal events to Processor
d. Processor Service
- Receives trigger events
- Reads zap definitions and scheduling logic
- Enqueues jobs for Worker
e. Worker Service
- Listens to job queue or outbox for tasks
- Executes side-effects:
- Email service (verification, password reset)
- Blockchain integrations (Ethereum, Solana)
f. Database
- Central PostgreSQL (or similar) accessed by Prisma in all services
g. External Services
- SMTP/email provider
- Ethereum node / RPC provider
- Solana RPC provider

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actors
    User["User"]:::external

    %% UI Layer
    subgraph "UI Layer"
        FE["Frontend (Next.js)"]:::frontend
        FE_pages_page["app/page.tsx"]:::frontend
        FE_pages_login["app/login/page.tsx"]:::frontend
        FE_pages_signup["app/signup/page.tsx"]:::frontend
        FE_pages_dashboard["app/dashboard/page.tsx"]:::frontend
        FE_pages_zap["app/zap/create/page.tsx"]:::frontend
        FE_components["components/"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        API["Primary-backend API"]:::api
        UR["user.ts"]:::api
        ZR["zap.ts"]:::api
        TR["trigger.ts"]:::api
        AR["action.ts"]:::api
        DB_index["db/index.ts"]:::api
        schema_prisma["schema.prisma"]:::api
        migrations_pb["prisma/migrations/"]:::api
    end

    %% Hooks Service
    subgraph "Hooks Service"
        Hooks["hooks/src/index.ts"]:::micro
        schema_hooks["schema.prisma"]:::micro
        migrations_hooks["prisma/migrations/"]:::micro
    end

    %% Processor Service
    subgraph "Processor Service"
        Proc["processor/src/index.ts"]:::micro
        schema_proc["schema.prisma"]:::micro
        migrations_proc["prisma/migrations/"]:::micro
    end

    %% Worker Service
    subgraph "Worker Service"
        Work["worker/src/index.ts"]:::micro
        email_ts["email.ts"]:::micro
        eth_ts["eth.ts"]:::micro
        sol_ts["solana.ts"]:::micro
        parser_ts["parser.ts"]:::micro
        schema_work["schema.prisma"]:::micro
        migrations_work["prisma/migrations/"]:::micro
    end

    %% Data Stores
    DB["PostgreSQL Database"]:::database
    Outbox["Outbox Table"]:::database

    %% External Services
    subgraph "External Services"
        EmailSvc["SMTP/Email Provider"]:::external
        EthSvc["Ethereum RPC"]:::external
        SolSvc["Solana RPC"]:::external
    end

    %% Connections
    User -->|"Uses (Browser)"| FE
    FE -->|"HTTP"| API
    API -->|"SQL (CRUD)"| DB
    API -->|"SQL (Writes Outbox)"| Outbox
    Outbox -->|"Poll (SQL)"| Hooks
    Outbox -->|"Poll (SQL)"| Proc
    Hooks -->|"Webhook/HTTP"| Proc
    Proc -->|"Queue"| Work
    Work -->|"SMTP"| EmailSvc
    Work -->|"RPC"| EthSvc
    Work -->|"RPC"| SolSvc

    %% Click Events
    click FE "https://github.com/heymustafa02/zapy/tree/main/frontend/"
    click FE_pages_page "https://github.com/heymustafa02/zapy/blob/main/frontend/app/page.tsx"
    click FE_pages_login "https://github.com/heymustafa02/zapy/blob/main/frontend/app/login/page.tsx"
    click FE_pages_signup "https://github.com/heymustafa02/zapy/blob/main/frontend/app/signup/page.tsx"
    click FE_pages_dashboard "https://github.com/heymustafa02/zapy/blob/main/frontend/app/dashboard/page.tsx"
    click FE_pages_zap "https://github.com/heymustafa02/zapy/blob/main/frontend/app/zap/create/page.tsx"
    click FE_components "https://github.com/heymustafa02/zapy/tree/main/frontend/components/"

    click API "https://github.com/heymustafa02/zapy/tree/main/primary-backend/"
    click UR "https://github.com/heymustafa02/zapy/blob/main/primary-backend/src/router/user.ts"
    click ZR "https://github.com/heymustafa02/zapy/blob/main/primary-backend/src/router/zap.ts"
    click TR "https://github.com/heymustafa02/zapy/blob/main/primary-backend/src/router/trigger.ts"
    click AR "https://github.com/heymustafa02/zapy/blob/main/primary-backend/src/router/action.ts"
    click DB_index "https://github.com/heymustafa02/zapy/blob/main/primary-backend/src/db/index.ts"
    click schema_prisma "https://github.com/heymustafa02/zapy/blob/main/primary-backend/prisma/schema.prisma"
    click migrations_pb "https://github.com/heymustafa02/zapy/tree/main/primary-backend/prisma/migrations/"

    click Hooks "https://github.com/heymustafa02/zapy/blob/main/hooks/src/index.ts"
    click schema_hooks "https://github.com/heymustafa02/zapy/blob/main/hooks/prisma/schema.prisma"
    click migrations_hooks "https://github.com/heymustafa02/zapy/tree/main/hooks/prisma/migrations/"

    click Proc "https://github.com/heymustafa02/zapy/blob/main/processor/src/index.ts"
    click schema_proc "https://github.com/heymustafa02/zapy/blob/main/processor/prisma/schema.prisma"
    click migrations_proc "https://github.com/heymustafa02/zapy/tree/main/processor/prisma/migrations/"

    click Work "https://github.com/heymustafa02/zapy/blob/main/worker/src/index.ts"
    click email_ts "https://github.com/heymustafa02/zapy/blob/main/worker/src/email.ts"
    click eth_ts "https://github.com/heymustafa02/zapy/blob/main/worker/src/eth.ts"
    click sol_ts "https://github.com/heymustafa02/zapy/blob/main/worker/src/solana.ts"
    click parser_ts "https://github.com/heymustafa02/zapy/blob/main/worker/src/parser.ts"
    click schema_work "https://github.com/heymustafa02/zapy/blob/main/worker/prisma/schema.prisma"
    click migrations_work "https://github.com/heymustafa02/zapy/tree/main/worker/prisma/migrations/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#3399ff,color:#000
    classDef api fill:#d4edda,stroke:#28a745,color:#000
    classDef micro fill:#fff3cd,stroke:#ffc107,color:#000
    classDef database fill:#e2e3e5,stroke:#6c757d,color:#000
    classDef external fill:#f8f9fa,stroke:#6c757d,color:#000
```
