# ad-on-is/rachoon architecture

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

- Interactive diagram: https://gitdiagram.com/ad-on-is/rachoon
- Repository: https://github.com/ad-on-is/rachoon

## Overview

##### Project type and purpose
- This is a full-stack, self-hosted invoicing platform (“Rachoon”) built as a monorepo (pnpm/Turbo).
- Frontend: Nuxt.js SPA/SSR.
- Backend: AdonisJS REST/JSON API.
- Database: PostgreSQL.
- External PDF service: Gotenberg.

##### File structure
- Top-level “apps” folder houses two deployable services:
- apps/frontend → Nuxt.js application
- apps/backend → AdonisJS application
- “packages/common” holds shared TypeScript models and utilities.
- Root contains Dockerfiles, docker-compose.yaml, Caddyfile, entrypoint, workspace configs (pnpm/turbo).
- Backend follows MVC: Controllers, Models, Services, Validators, Middleware.
- Frontend is component-based (Vue components, composables, pages, plugins, layouts).

##### Extract key details from the README
- Confirms tech stack: Nuxt.js, AdonisJS, PostgreSQL, Gotenberg, Docker.
- Deployment via Docker Compose with three containers: rachoon (backend+frontend?), gotenberg, postgres.
- Emphasizes self-hosted, API-driven invoicing, templating via nunjucks.

##### Components and interactions
a. Main components
- Browser / User Agent
- Caddy (Reverse Proxy / TLS / Static assets)
- Nuxt.js Frontend (SSR/API Proxy)
- AdonisJS Backend (REST API, Auth, Business Logic)
- PostgreSQL Database
- Gotenberg PDF Service
- Shared Library (packages/common)
b. Relationships & data flow
1. Browser → Caddy (HTTP/HTTPS)
2. Caddy → Nuxt (static assets & SSR)
3. Nuxt → AdonisJS (API calls: auth, CRUD on clients, invoices, templates)
4. AdonisJS → PostgreSQL (ORM/knex queries)
5. AdonisJS → Gotenberg (PDF rendering via HTTP)
6. AdonisJS & Nuxt both import/shared models from packages/common
c. Architectural patterns & principles
- Monorepo with shared domain models (DRY).
- Backend: MVC + Service layer + Middleware pipeline.
- Frontend: Component-driven architecture + composables/hooks.
- Reverse proxy pattern (Caddy).
- Containerized microservices for PDF & DB.
d. Key technologies
- Vue 3 / Nuxt 3, Pinia, Tailwind
- AdonisJS, TypeScript, Knex/Query Builder
- PostgreSQL
- Gotenberg (Dockerized)
- Docker Compose, Caddy, pnpm, TurboRepo

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    Browser["Browser / User Agent"]:::user
    Browser -->|"HTTP/HTTPS"| Caddy

    subgraph "Docker Compose" 
        direction TB
        Caddy["Caddy<br/>(Reverse Proxy / TLS / Static assets)"]:::proxy
        Nuxt["Nuxt.js Frontend<br/>(SPA/SSR)"]:::frontend
        Adonis["AdonisJS Backend<br/>(REST API)"]:::backend
        Postgres["PostgreSQL Database"]:::database
        Gotenberg["Gotenberg PDF Service"]:::external

        Caddy -->|"serves SSR & assets"| Nuxt
        Nuxt -->|"HTTP API"| Adonis
        Adonis -->|"SQL queries / ORM"| Postgres
        Adonis -->|"HTTP PDF render"| Gotenberg
    end

    %% Shared library
    Common["Shared Library<br/>(packages/common)"]:::common
    Common -.->|build-time dependency| Nuxt
    Common -.->|build-time dependency| Adonis

    %% AdonisJS internal components
    subgraph "AdonisJS App" 
        direction TB
        Controllers["Controllers"]:::backendComp
        Models["Models"]:::backendComp
        Services["Services"]:::backendComp
        Middleware["Middleware"]:::backendComp
        Validators["Validators"]:::backendComp

        Adonis --> Controllers
        Adonis --> Models
        Adonis --> Services
        Adonis --> Middleware
        Adonis --> Validators

        Services -->|uses Renderer.ts| Gotenberg
    end

    %% Click events
    click Caddy "https://github.com/ad-on-is/rachoon/tree/main/Caddyfile"
    click DockerCompose "https://github.com/ad-on-is/rachoon/blob/main/docker-compose.yaml"
    click Nuxt "https://github.com/ad-on-is/rachoon/tree/main/apps/frontend"
    click Nuxt "https://github.com/ad-on-is/rachoon/blob/main/apps/frontend/nuxt.config.ts"
    click Adonis "https://github.com/ad-on-is/rachoon/blob/main/apps/backend/server.ts"
    click Adonis "https://github.com/ad-on-is/rachoon/blob/main/apps/backend/start/routes.ts"
    click Controllers "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/app/Controllers/Http"
    click Models "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/app/Models"
    click Services "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/app/Services"
    click Middleware "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/app/Middleware"
    click Validators "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/app/Validators"
    click Postgres "https://github.com/ad-on-is/rachoon/blob/main/apps/backend/config/database.ts"
    click Postgres "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/database/migrations"
    click Postgres "https://github.com/ad-on-is/rachoon/tree/main/apps/backend/database/seeders"
    click Gotenberg "https://github.com/ad-on-is/rachoon/blob/main/apps/backend/app/Services/Renderer.ts"
    click Gotenberg "https://github.com/ad-on-is/rachoon/blob/main/apps/backend/app/Controllers/Http/RenderController.ts"
    click Common "https://github.com/ad-on-is/rachoon/tree/main/packages/common/src"

    %% Styles
    classDef user fill:#f9f,stroke:#333,stroke-width:1px
    classDef proxy fill:#bbf,stroke:#333,stroke-width:1px
    classDef frontend fill:#bfb,stroke:#333,stroke-width:1px
    classDef backend fill:#fbf,stroke:#333,stroke-width:1px
    classDef database fill:#ffb,stroke:#333,stroke-width:1px
    classDef external fill:#fbb,stroke:#333,stroke-width:1px
    classDef common fill:#fcf,stroke:#333,stroke-width:1px
    classDef backendComp fill:#ffe,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
