# artreeus/invoicer_pro architecture

> Architecture diagram of the GitHub repository artreeus/invoicer_pro, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/artreeus/invoicer_pro
- Repository: https://github.com/artreeus/invoicer_pro

## Overview

1. **Overall shape**
   - This is a monorepo for an invoicing product with three major parts:
     - a **React/Vite frontend** in `src/`
     - a **Node/Express-style backend** in `server/` plus `api/` entrypoint for deployment
     - a **Supabase database layer** defined by SQL migrations in `supabase/migrations/`

2. **Two distinct user-facing surfaces**
   - The app is split between:
     - a **public marketing/content site**: landing page, blog, contact, privacy/terms, templates gallery, and a public invoice generator
     - a **protected authenticated app**: dashboard, invoices, clients, companies, reports, settings, and item library
   - This boundary is enforced in the frontend with auth wrappers like `RequireAuth` and separate public/private layouts.

3. **Frontend shell and routing**
   - `src/main.tsx`, `src/App.tsx`, and the page components in `src/pages/` define the app composition.
   - Layout components in `src/components/layout/` and `src/components/public/` provide the chrome for the authenticated area versus public pages.
   - The structure suggests the frontend is the primary application shell, with most business interactions happening client-side.

4. **State management by domain**
   - `src/store/` contains dedicated stores for the core business entities:
     - `authStore`
     - `clientStore`
     - `companyStore`
     - `invoiceStore`
     - `itemLibraryStore`
     - `themeStore`
   - These stores likely coordinate API calls, local UI state, and cross-page data persistence for each domain.

5. **Core business domains**
   - The app revolves around four main data entities:
     - **companies**
     - **clients**
     - **invoices**
     - **invoice items / item library**
   - Pages like `CompaniesPage`, `ClientsPage`, `InvoicesPage`, `InvoiceFormPage`, and `ItemLibraryPage` map directly to these domains.
   - `InvoicePreviewPage` and `exportUtils` indicate a render/export workflow for invoice output.

6. **Invoice template engine**
   - `src/templates/` contains a large set of invoice themes such as Classic, Modern, Corporate, Minimal, Terminal, and others.
   - `src/templates/index.ts` and `shared.tsx` imply a template registry and common rendering contract.
   - This is a key architectural boundary: invoice data is separated from presentation, and different templates can render the same invoice model.

7. **Backend responsibilities**
   - `server/app.js`, `server/index.js`, `server/auth.js`, `server/db.js`, and `server/cloudinary.js` suggest a lightweight backend focused on:
     - authentication/session handling
     - database access
     - file/image upload integration
     - serving API routes
   - `api/index.js` likely provides the deployment entrypoint for serverless hosting on Vercel, matching the presence of `vercel.json`.

8. **Database and access control**
   - The schema lives in Supabase migrations for `companies`, `clients`, `invoices`, `invoice_items`, and `item_library`.
   - Later migrations explicitly mention **RLS policy tightening** and insert-policy adjustments, so row-level security is a meaningful part of the architecture.
   - This means the backend/frontend likely rely on Supabase for persistence, with database access constrained by per-user policies.

9. **External services**
   - `src/lib/cloudinary.ts` and `server/cloudinary.js` show Cloudinary is used for image storage or uploads.
   - `src/lib/adsense.ts` plus `src/components/ads/` indicate Google AdSense is integrated into the public content side.
   - `src/lib/useSeo.ts` and public article/content components suggest SEO is handled carefully for the marketing/blog surface.

10. **Public content and SEO**
   - `src/content/articles.ts` and `src/pages/public/Blog*` suggest the blog is content-driven and likely static or semi-static.
   - Public pages such as About, Contact, Privacy, Terms, and Templates are separated from the logged-in app to support discovery, trust, and SEO.

11. **UI and reusable building blocks**
   - `src/components/ui/` provides shared primitives such as `Modal`, `Badge`, `EmptyState`, `ThemeToggle`, and image upload components.
   - `AuthShell` and `PublicLayout` are higher-level composition layers that keep auth flows and public pages visually distinct.
   - This indicates a componentized frontend with reusable design-system-like building blocks.

12. **Platform and deployment signals**
   - The app is built with **Vite**, **React**, **TypeScript**, and **Tailwind/PostCSS**.
   - `vercel.json`, `api/`, and `api/index.js` suggest deployment on Vercel, with the frontend and backend co-located but separated by runtime boundary.
   - Supabase migrations imply the database is managed outside the app runtime and versioned alongside the code.

13. **Likely end-to-end data flow**
   - User interacts with the React UI.
   - Frontend stores coordinate domain state and call the API layer.
   - Backend authenticates requests and communicates with Supabase and Cloudinary.
   - Supabase persists the invoicing entities under RLS.
   - The UI renders invoice previews/templates and may export or download final invoice artifacts.

14. **What to show in an architecture diagram**
   - Draw three main zones:
     - **Public frontend**
     - **Authenticated app frontend**
     - **Backend/API + Supabase/Cloudinary services**
   - Emphasize the domain data path around clients/companies/invoices/items, and the separate content/SEO/ads path for public pages.

Main entry points: [`src/components/layout/Layout.tsx`](https://github.com/artreeus/invoicer_pro/blob/main/src/components/layout/Layout.tsx) (App layout), [`src/templates/index.ts`](https://github.com/artreeus/invoicer_pro/blob/main/src/templates/index.ts) (Template engine), [`src/pages/InvoicesPage.tsx`](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoicesPage.tsx) (Invoices), [`server/app.js`](https://github.com/artreeus/invoicer_pro/blob/main/server/app.js) (Server API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend_public["Public frontend"]
  node_public_shell["Public layout<br/>public chrome<br/>[PublicLayout.tsx]"]
  node_landing["Landing<br/>marketing page<br/>[LandingPage.tsx]"]
  node_content_site["Content site<br/>public pages<br/>[BlogIndexPage.tsx]"]
  node_invoice_generator["Generator<br/>public tool"]
  node_templates{{"Template engine<br/>render system<br/>[index.ts]"}}
end

subgraph group_frontend_app["Authenticated app"]
  node_main_app(("App shell<br/>react entry<br/>[main.tsx]"))
  node_app_routes["Routing<br/>route composition<br/>[App.tsx]"]
  node_auth_guard["Auth guard<br/>access control<br/>[RequireAuth.tsx]"]
  node_auth_shell["Auth shell<br/>app chrome<br/>[AuthShell.tsx]"]
  node_private_layout["App layout<br/>[Layout.tsx]"]
  node_dashboard["Dashboard<br/>private page<br/>[Dashboard.tsx]"]
  node_invoice_workflow["Invoices<br/>billing pages<br/>[InvoicesPage.tsx]"]
  node_invoice_form["Invoice form<br/>editor page"]
  node_invoice_preview["Preview<br/>render page"]
  node_clients["Clients<br/>domain page<br/>[ClientsPage.tsx]"]
  node_companies["Companies<br/>domain page<br/>[CompaniesPage.tsx]"]
  node_items["Item library<br/>domain page"]
  node_reports["Reports<br/>analytics page<br/>[ReportsPage.tsx]"]
  node_settings["Settings<br/>preferences page<br/>[SettingsPage.tsx]"]
  node_stores["Domain stores<br/>state layer<br/>[invoiceStore.ts]"]
end

subgraph group_platform_data["Backend and data"]
  node_frontend_api["API client<br/>data access<br/>[api.ts]"]
  node_server_api["Server API<br/>backend app<br/>[app.js]"]
  node_auth_db[("Auth + DB<br/>backend services<br/>[auth.js]")]
end

node_main_app -->|"boots"| node_app_routes
node_app_routes -->|"protects"| node_auth_guard
node_auth_guard -->|"wraps"| node_auth_shell
node_auth_shell -->|"uses"| node_private_layout
node_private_layout -->|"navigates"| node_dashboard
node_private_layout -->|"navigates"| node_invoice_workflow
node_private_layout -->|"navigates"| node_clients
node_private_layout -->|"navigates"| node_companies
node_private_layout -->|"navigates"| node_items
node_private_layout -->|"navigates"| node_reports
node_private_layout -->|"navigates"| node_settings
node_invoice_workflow -->|"edits"| node_invoice_form
node_invoice_workflow -->|"renders"| node_invoice_preview
node_stores -->|"fetches"| node_frontend_api
node_frontend_api -->|"calls"| node_server_api
node_server_api -->|"uses"| node_auth_db
node_server_api -.->|"serves data"| node_templates
node_invoice_preview -->|"uses"| node_templates
node_landing -->|"uses"| node_public_shell
node_content_site -->|"uses"| node_public_shell
node_invoice_generator -->|"uses"| node_public_shell
node_content_site -->|"showcases"| node_templates
node_invoice_generator -->|"renders"| node_templates

click node_main_app "https://github.com/artreeus/invoicer_pro/blob/main/src/main.tsx"
click node_app_routes "https://github.com/artreeus/invoicer_pro/blob/main/src/App.tsx"
click node_auth_guard "https://github.com/artreeus/invoicer_pro/blob/main/src/components/auth/RequireAuth.tsx"
click node_auth_shell "https://github.com/artreeus/invoicer_pro/blob/main/src/components/auth/AuthShell.tsx"
click node_private_layout "https://github.com/artreeus/invoicer_pro/blob/main/src/components/layout/Layout.tsx"
click node_dashboard "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/Dashboard.tsx"
click node_invoice_workflow "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoicesPage.tsx"
click node_invoice_form "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoiceFormPage.tsx"
click node_invoice_preview "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoicePreviewPage.tsx"
click node_clients "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/ClientsPage.tsx"
click node_companies "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/CompaniesPage.tsx"
click node_items "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/ItemLibraryPage.tsx"
click node_reports "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/ReportsPage.tsx"
click node_settings "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/SettingsPage.tsx"
click node_public_shell "https://github.com/artreeus/invoicer_pro/blob/main/src/components/public/PublicLayout.tsx"
click node_landing "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/LandingPage.tsx"
click node_content_site "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/public/BlogIndexPage.tsx"
click node_invoice_generator "https://github.com/artreeus/invoicer_pro/blob/main/src/pages/public/InvoiceGeneratorPage.tsx"
click node_templates "https://github.com/artreeus/invoicer_pro/blob/main/src/templates/index.ts"
click node_stores "https://github.com/artreeus/invoicer_pro/blob/main/src/store/invoiceStore.ts"
click node_frontend_api "https://github.com/artreeus/invoicer_pro/blob/main/src/lib/api.ts"
click node_server_api "https://github.com/artreeus/invoicer_pro/blob/main/server/app.js"
click node_auth_db "https://github.com/artreeus/invoicer_pro/blob/main/server/auth.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_public_shell,node_landing,node_content_site,node_invoice_generator,node_templates toneBlue
class node_main_app,node_app_routes,node_auth_guard,node_auth_shell,node_private_layout,node_dashboard,node_invoice_workflow,node_invoice_form,node_invoice_preview,node_clients,node_companies,node_items,node_reports,node_settings,node_stores toneAmber
class node_frontend_api,node_server_api,node_auth_db toneMint
```

## Components

### Public frontend

Marketing, blog, SEO, and public invoice tools.

- [Public layout](https://github.com/artreeus/invoicer_pro/blob/main/src/components/public/PublicLayout.tsx): public chrome · Layout for marketing and content pages. · `src/components/public/PublicLayout.tsx`
- [Landing](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/LandingPage.tsx): marketing page · Public home and product introduction. · `src/pages/LandingPage.tsx`
- [Content site](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/public/BlogIndexPage.tsx): public pages · Blog, about, contact, legal, and templates pages. · `src/pages/public/BlogIndexPage.tsx`
- [Generator](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/public/InvoiceGeneratorPage.tsx): public tool · Public invoice generation surface. · `src/pages/public/InvoiceGeneratorPage.tsx`
- [Template engine](https://github.com/artreeus/invoicer_pro/blob/main/src/templates/index.ts): render system · Invoice template registry and shared rendering contract. · `src/templates/index.ts`

### Authenticated app

Protected invoicing workspace and shared frontend shell.

- [App shell](https://github.com/artreeus/invoicer_pro/blob/main/src/main.tsx): react entry · Bootstraps the React application. · `src/main.tsx`
- [Routing](https://github.com/artreeus/invoicer_pro/blob/main/src/App.tsx): route composition · Top-level routing and page composition. · `src/App.tsx`
- [Auth guard](https://github.com/artreeus/invoicer_pro/blob/main/src/components/auth/RequireAuth.tsx): access control · Protects private app routes. · `src/components/auth/RequireAuth.tsx`
- [Auth shell](https://github.com/artreeus/invoicer_pro/blob/main/src/components/auth/AuthShell.tsx): app chrome · Layout wrapper for signed-in views. · `src/components/auth/AuthShell.tsx`
- [App layout](https://github.com/artreeus/invoicer_pro/blob/main/src/components/layout/Layout.tsx): layout · Shared navigation chrome for the dashboard area. · `src/components/layout/Layout.tsx`
- [Dashboard](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/Dashboard.tsx): private page · Signed-in landing page. · `src/pages/Dashboard.tsx`
- [Invoices](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoicesPage.tsx): billing pages · Invoice list, edit, and preview flow. · `src/pages/InvoicesPage.tsx`
- [Invoice form](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoiceFormPage.tsx): editor page · Create and edit invoice records. · `src/pages/InvoiceFormPage.tsx`
- [Preview](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/InvoicePreviewPage.tsx): render page · Renders invoice output for review and export. · `src/pages/InvoicePreviewPage.tsx`
- [Clients](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/ClientsPage.tsx): domain page · Client management screen. · `src/pages/ClientsPage.tsx`
- [Companies](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/CompaniesPage.tsx): domain page · Company profile and billing identity management. · `src/pages/CompaniesPage.tsx`
- [Item library](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/ItemLibraryPage.tsx): domain page · Reusable invoice line items and catalog data. · `src/pages/ItemLibraryPage.tsx`
- [Reports](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/ReportsPage.tsx): analytics page · Business reporting and summaries. · `src/pages/ReportsPage.tsx`
- [Settings](https://github.com/artreeus/invoicer_pro/blob/main/src/pages/SettingsPage.tsx): preferences page · User and app settings. · `src/pages/SettingsPage.tsx`
- [Domain stores](https://github.com/artreeus/invoicer_pro/blob/main/src/store/invoiceStore.ts): state layer · Client, company, invoice, item, auth, and theme state. · `src/store/invoiceStore.ts`

### Backend and data

API runtime, persistence, uploads, and deployment boundary.

- [API client](https://github.com/artreeus/invoicer_pro/blob/main/src/lib/api.ts): data access · Frontend calls into backend and external services. · `src/lib/api.ts`
- [Server API](https://github.com/artreeus/invoicer_pro/blob/main/server/app.js): backend app · Express-style application and deployment entrypoint. · `server/app.js`
- [Auth + DB](https://github.com/artreeus/invoicer_pro/blob/main/server/auth.js): backend services · Authentication helpers and database access. · `server/auth.js`

## Connections

- App shell → Routing: boots · Entry point mounts the application routes.
- Routing → Auth guard: protects · Private routes pass through auth enforcement.
- Auth guard → Auth shell: wraps · Signed-in experience is rendered inside the auth shell.
- Auth shell → App layout: uses · Auth shell composes the app layout.
- App layout → Dashboard: navigates · Main shell routes into the dashboard.
- App layout → Invoices: navigates · Shell links into invoice management.
- App layout → Clients: navigates · Shell links into client management.
- App layout → Companies: navigates · Shell links into company management.
- App layout → Item library: navigates · Shell links into the item library.
- App layout → Reports: navigates · Shell links into reporting.
- App layout → Settings: navigates · Shell links into settings.
- Invoices → Invoice form: edits · Invoice list flows into the editor.
- Invoices → Preview: renders · Invoices can be previewed before output.
- Domain stores → API client: fetches · Domain stores coordinate API calls and local state.
- API client → Server API: calls · Frontend communicates with the backend runtime.
- Server API → Auth + DB: uses · Server handles auth and persistence access.
- Server API → Template engine: serves data · Backend supports invoice rendering workflows.
- Preview → Template engine: uses · Preview page renders through the template system.
- Landing → Public layout: uses · Public pages share the marketing layout.
- Content site → Public layout: uses · Blog and legal content use the public shell.
- Generator → Public layout: uses · Public tool is presented in the public layout.
- Content site → Template engine: showcases · Template gallery and content surface reference invoice themes.
- Generator → Template engine: renders · Public generator produces invoices via templates.