# al1abb/invoify architecture

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

- Interactive diagram: https://gitdiagram.com/al1abb/invoify
- Repository: https://github.com/al1abb/invoify

## Overview

##### Main Components Identification
- Frontend/UI Layer:
- Represented by the Next.js app directory (e.g., app/[locale], the layout files, page.tsx files).
- Contains sophisticated UI elements (invoice forms, modals, live preview components) and reusable UI components defined in app/components and components/ui.
- Includes internationalization (i18n/locales) and theming (contexts/ThemeProvider) support.
- API/Backend Endpoints:
- Located under app/api/invoice with separate routes for generating PDFs, exporting invoices, and sending them via email.
- These API endpoints act as the bridge between the frontend and server-side processes.
- Service Layer:
- Found in the services/invoice directory with client and server implementations.
- Manages business logic such as PDF generation (using Puppeteer), invoice export, and email sending (using Nodemailer).
- Utility and Shared Libraries:
- Helper functions, schemas, and utility modules in the lib directory.
- Custom hooks and context providers (under hooks and contexts respectively) that facilitate state management and reusability.

##### Relationships and Interactions
- UI Components → API Endpoints:
- API Endpoints → Services:
- Service Layer → External Resources:
- Context Providers and Hooks:
- State management layers (e.g., InvoiceContext, ChargesContext) and utility hooks that bridge interactions between UI components and the underlying state or API calls.

##### Architectural Patterns & Design Principles
- Component-based architecture with separation between presentation (React components) and business/service logic.
- Clear separation between frontend rendering and server-side logic provided by Next.js API routes.
- Use of design patterns such as modularization (dividing components into invoice, modals, reusables) and single responsibility (each API/service method handles a specific invoice action).

##### Technologies and Frameworks
- Next.js 13 & React (SSR, client-side routing, app directory structure).
- TypeScript for type safety.
- Shadcn UI and Tailwind CSS for UI styling.
- Puppeteer for server-side PDF generation.
- Nodemailer for sending emails.
- Internationalization via i18n and multiple locale files.

##### Putting It All Together
- Endpoints to the service layer:
- Finally, highlight external libraries:
- Puppeteer and Nodemailer as external dependencies that the services interact with.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        UI1["Main App Layout & Pages"]:::frontend
        UI2["Invoice UI Components (App)"]:::frontend
        UI3["Invoice UI Components (UI)"]:::frontend
        UI4["Modals & Reusables"]:::frontend
        UI5["Internationalization & Context Providers"]:::frontend
    end

    %% API Layer
    subgraph "API/Backend Endpoints"
        API1["Generate Invoice API"]:::api
        API2["Export Invoice API"]:::api
        API3["Send Invoice API"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        SVC1["Generate PDF Service"]:::service
        SVC2["Export Invoice Client"]:::service
        SVC3["Export Invoice Service"]:::service
        SVC4["Send PDF Email Service"]:::service
    end

    %% Utility & Shared Libraries
    subgraph "Utilities & Shared Libraries"
        UTIL1["Helper Functions"]:::utility
        UTIL2["Custom Hooks"]:::utility
        UTIL3["Context Providers"]:::utility
        UTIL4["Internationalization Files"]:::utility
    end

    %% External Dependencies
    subgraph "External Dependencies"
        EXT1["Puppeteer"]:::external
        EXT2["Nodemailer"]:::external
    end

    %% Relationships - UI Layer to API
    UI2 -->|"generate-invoice"| API1
    UI2 -->|"export-invoice"| API2
    UI2 -->|"send-invoice"| API3
    UI3 -->|"user-actions"| API1
    UI3 -->|"user-actions"| API2
    UI3 -->|"user-actions"| API3
    UI5 -->|"provides-context"| UI2
    UI5 -->|"provides-context"| UI3

    %% Relationships - API to Services
    API1 -->|"calls"| SVC1
    API2 -->|"calls"| SVC2
    API2 -->|"calls"| SVC3
    API3 -->|"calls"| SVC4

    %% Relationships - Services to External Dependencies
    SVC1 -->|"uses"| EXT1
    SVC4 -->|"uses"| EXT2

    %% Relationships - Utilities usage
    UTIL1 -->|"supports"| SVC1
    UTIL1 -->|"supports"| API1
    UTIL2 -->|"enhances"| UI2
    UTIL2 -->|"enhances"| UI3
    UTIL3 -->|"wraps"| UI5

    %% Click Events for Frontend/UI Layer
    click UI1 "https://github.com/al1abb/invoify/blob/master/app/layout.tsx"
    click UI2 "https://github.com/al1abb/invoify/tree/master/app/components/invoice"
    click UI3 "https://github.com/al1abb/invoify/tree/master/components/ui"
    click UI5 "https://github.com/al1abb/invoify/blob/master/contexts/ThemeProvider.tsx"

    %% Click Events for API Endpoints
    click API1 "https://github.com/al1abb/invoify/blob/master/app/api/invoice/generate/route.ts"
    click API2 "https://github.com/al1abb/invoify/blob/master/app/api/invoice/export/route.ts"
    click API3 "https://github.com/al1abb/invoify/blob/master/app/api/invoice/send/route.ts"

    %% Click Events for Service Layer
    click SVC1 "https://github.com/al1abb/invoify/blob/master/services/invoice/server/generatePdfService.ts"
    click SVC2 "https://github.com/al1abb/invoify/blob/master/services/invoice/client/exportInvoice.ts"
    click SVC3 "https://github.com/al1abb/invoify/blob/master/services/invoice/server/exportInvoiceService.ts"
    click SVC4 "https://github.com/al1abb/invoify/blob/master/services/invoice/server/sendPdfToEmailService.ts"

    %% Click Events for Utility & Shared Libraries
    click UTIL1 "https://github.com/al1abb/invoify/blob/master/lib/helpers.ts"
    click UTIL2 "https://github.com/al1abb/invoify/blob/master/hooks/useCurrencies.tsx"
    click UTIL3 "https://github.com/al1abb/invoify/blob/master/contexts/InvoiceContext.tsx"
    click UTIL4 "https://github.com/al1abb/invoify/blob/master/i18n/locales/en.json"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef api fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef service fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef utility fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
```
