# legions-developer/invoicely architecture

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

- Interactive diagram: https://gitdiagram.com/legions-developer/invoicely
- Repository: https://github.com/legions-developer/invoicely

## Overview

##### Project type and purpose
- This is a monorepo for a **client-heavy Next.js 13** application (“Invoicely”) plus a set of shared packages (eslint-config, typescript-config, utilities).
- Purpose: A browser-based invoice generator that stores invoices in IndexedDB, renders them to PDF via a web worker, and ships as a static/SSR Next.js app.

##### File structure
- Top‐level:
- apps/web – the Next.js “app router” codebase (pages, layouts, components, hooks, providers, lib, content)
- packages – shared config and utility libraries
- turbo.json, yarn workspaces
- apps/web layers:
- src/app – routes (marketing + dashboard features)
- src/components – design system (ui, layout, pdf, sidebar)
- src/global + src/lib – state management (Jotai atoms), IndexedDB wrappers, PDF helpers
- src/providers – context providers for Jotai, PDF web worker, analytics
- Key config: next.config.ts, tsconfig.json, postcss, ESLint, Husky

##### Extract insights from README
- It’s a zero-backend, purely front-end invoicing app.
- Build uses `yarn build` via TurboRepo, runs Next.js build pipelines.
- Routes are pre-rendered or server-rendered for marketing and static-dynamic dashboards.

##### Main components
a. Monorepo orchestrator (TurboRepo + Yarn Workspaces)
b. Web Application (Next.js)
– UI Layer: React components & layouts
– Routing Layer: App Router (server + client components)
– Data Layer: Jotai state + hooks
– Persistence: IndexedDB (via `src/global/indexdb` + lib/indexdb-queries)
– PDF Engine: PDF web worker (via `providers/pdf-worker-provider`)
– Content Layer: MDX content + public assets
c. Shared Packages (eslint-config, tsconfig, utilities)
d. External Services
– Analytics (PostHog, OneDollarStats, OpenPanel)
– Fonts, CDN, static hosting

##### Relationships and interactions
- Developer triggers `yarn dev|build` at root → TurboRepo invokes Next.js build in apps/web and compiles shared packages
- End user → Browser → Next.js server/static page → React renders UI
- UI dispatches actions → Jotai atoms → persistence layer → IndexedDB
- “Export invoice” → UI calls PDF web worker → returns blob → browser download
- Throughout session → Analytics provider → external analytics endpoint

##### Architectural patterns & design principles
- Monorepo with code-sharing via workspaces
- Feature-based folder structure under `src/app` (marketing vs dashboard)
- UI components organized by domain (ui/, layout/, pdf/)
- Separation of concerns: UI vs state vs persistence vs side effects
- Use of web worker for CPU-intensive PDF generation
- App Router (server/client component split) for SSR/SSG optimization

- Clear component labels (e.g., “Next.js App Router”, “Jotai Store”, “PDF Web Worker”)
- Rectangles for code modules

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Top Layer: Developer Tools
    subgraph "Developer Tools"
        direction TB
        ORG_Turbo["TurboRepo"]:::tooling
        ORG_Yarn["Yarn Workspaces"]:::tooling
    end

    %% Middle Layer: Next.js Application
    subgraph "Next.js Application"
        direction TB

        %% Routing Layer
        subgraph "Routing Layer"
            direction TB
            Router["Next.js App Router<br/>(src/app)"]:::backend
            Layout["layout.tsx"]:::backend
            Page["page.tsx"]:::backend
            Marketing["marketing/"]:::backend
            Dashboard["dashboard/"]:::backend
        end

        %% UI Layer
        subgraph "UI Layer"
            direction TB
            UI_Components["Components (ui/)"]:::ui
            Layout_Marketing["Marketing Layouts (layout/marketing/)"]:::ui
            Layout_Sidebar["Sidebar Layouts (layout/sidebar/)"]:::ui
            PDF_UI["PDF UI (pdf/)"]:::ui
        end

        %% Data Layer
        subgraph "Data Layer"
            direction TB
            Atoms["Invoice Atom<br/>(atoms/invoice-atom.ts)"]:::data
            Hooks["Hooks (use-*.ts)"]:::data
        end

        %% Persistence Layer
        subgraph "Persistence Layer"
            direction TB
            IDB_Wrapper["IndexedDB Wrapper<br/>(global/indexdb/index.ts)"]:::data
            IDB_Queries["indexdb-queries/invoice.ts"]:::data
            IDB_Consts["IndexedDB Constants"]:::data
        end

        %% PDF Engine
        subgraph "PDF Engine"
            direction TB
            WorkerProvider["PDF Web Worker Provider<br/>(pdf-worker-provider.tsx)"]:::worker
            CreateBlob["create-pdf-blob.tsx"]:::worker
            CreateURL["create-blob-url.ts"]:::worker
            DownloadFile["download-file.tsx"]:::worker
        end

        %% Content Layer
        subgraph "Content Layer"
            direction TB
            MDX["MDX Content (src/content/blogs/*.mdx)"]:::content
            PublicAssets["Public Assets (public/)"]:::content
        end

    end

    %% Bottom Layer: Shared Packages & External Services
    subgraph "Shared Packages"
        direction TB
        ESLintConfig["eslint-config/"]:::tooling
        TSConfig["typescript-config/"]:::tooling
        Utilities["utilities/"]:::tooling
    end

    subgraph "External Services"
        direction TB
        Analytics["Analytics Providers"]:::external
        FontsCDN["Fonts/CDN/Hosting"]:::external
    end

    %% Connections: Build & Runtime Flows
    ORG_Turbo -->|build| Router
    ORG_Yarn -->|build| Router

    %% User Interaction
    User["End User<br/>(Browser)"]:::external
    User -->|"HTTP Request"| Router
    Router -->|"renders"| UI_Components
    UI_Components -->|"dispatches"| Atoms
    Atoms -->|"reads/writes"| IDB_Wrapper
    IDB_Wrapper --> IDB_Queries
    IDB_Wrapper --> IDB_Consts
    UI_Components -->|"export invoice"| WorkerProvider
    WorkerProvider --> CreateBlob
    CreateBlob --> CreateURL
    CreateURL --> DownloadFile
    DownloadFile -->|"download blob"| User
    UI_Components --> MDX
    UI_Components --> PublicAssets

    %% Analytics
    subgraph AnalyticsFlow
        direction TB
        AnalyticsProvider["Providers (posthog/onedollarstats/openpanel)"]:::external
    end
    UI_Components -->|"track events"| AnalyticsProvider
    AnalyticsProvider --> Analytics

    %% Shared Packages Usage
    Router --> ESLintConfig
    Router --> TSConfig
    Router --> Utilities

    %% Click Events
    click ORG_Turbo "https://github.com/legions-developer/invoicely/blob/main/turbo.json"
    click ORG_Turbo "https://github.com/legions-developer/invoicely/blob/main/package.json"
    click ORG_Yarn "https://github.com/legions-developer/invoicely/tree/main/.yarn/"
    click ORG_Yarn "https://github.com/legions-developer/invoicely/blob/main/yarn.lock"
    click Layout "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/app/layout.tsx"
    click Page "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/app/page.tsx"
    click Marketing "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/app/marketing/"
    click Dashboard "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/app/dashboard/"
    click UI_Components "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/components/ui/"
    click Layout_Marketing "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/components/layout/marketing/"
    click Layout_Sidebar "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/components/layout/sidebar/"
    click PDF_UI "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/components/pdf/"
    click Atoms "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/global/atoms/invoice-atom.ts"
    click Hooks "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/hooks/"
    click IDB_Wrapper "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/global/indexdb/index.ts"
    click IDB_Queries "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/lib/indexdb-queries/invoice.ts"
    click IDB_Consts "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/constants/indexed-db.ts"
    click WorkerProvider "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/providers/pdf-worker-provider.tsx"
    click CreateBlob "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/lib/invoice/create-pdf-blob.tsx"
    click CreateURL "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/lib/invoice/create-blob-url.ts"
    click DownloadFile "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/lib/invoice/download-file.tsx"
    click MDX "https://github.com/legions-developer/invoicely/tree/main/apps/web/src/content/blogs/"
    click PublicAssets "https://github.com/legions-developer/invoicely/tree/main/apps/web/public/"
    click AnalyticsProvider "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/providers/posthog-provider.tsx"
    click AnalyticsProvider "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/providers/onedollarstats-provider.tsx"
    click AnalyticsProvider "https://github.com/legions-developer/invoicely/blob/main/apps/web/src/providers/openpanel-provider.tsx"
    click ESLintConfig "https://github.com/legions-developer/invoicely/tree/main/packages/eslint-config/"
    click TSConfig "https://github.com/legions-developer/invoicely/tree/main/packages/typescript-config/"
    click Utilities "https://github.com/legions-developer/invoicely/tree/main/packages/utilities/"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef data fill:#E6FFFA,stroke:#38A169,color:#2F855A
    classDef worker fill:#FFF5E6,stroke:#DD6B20,color:#C05621
    classDef tooling fill:#F0F0F0,stroke:#A0AEC0,color:#4A5568
    classDef backend fill:#E9E8FF,stroke:#7F5AF0,color:#6B46C1
    classDef content fill:#FFF0F6,stroke:#D53F8C,color:#97266D
    classDef external fill:#EDF2F7,stroke:#718096,color:#4A5568
```
