# ripwords/timesheet architecture

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

- Interactive diagram: https://gitdiagram.com/ripwords/timesheet
- Repository: https://github.com/ripwords/timesheet

## Overview

##### Project type and purpose
- This is a full-stack timesheet application organized as a monorepo.
- It comprises three main “apps”:
- A web dashboard (apps/dashboard) built with Nuxt 3 + Vue.
- A desktop client (apps/desktop) built with Nuxt + Tauri.
- A backend API server (apps/server) running on Bun + Drizzle ORM.
- The root also contains Docker/Docker-Compose configurations to spin up the system in containers.

##### Main components
a. Frontends
– Web Dashboard (Nuxt/Vue)
– Desktop Client (Nuxt + Tauri)
b. Backend API
– Bun runtime
– Entry point index.ts
– Module boundaries: auth, admin (departments, users, financials, reports, settings), projects, time-entries, time-tracker, services (cron jobs), middleware
c. Database
– PostgreSQL (drizzle.config.ts + drizzle migration/seed files)
d. External services
– SMTP/mail provider (apps/server/utils/mail.ts)
– Possible third-party auth/email (e.g., via Eden plugin)
e. Infrastructure
– Docker containers (web, desktop, api, database) orchestrated by docker-compose
– Entrypoint shell scripts (apps/server/entrypoint.sh)

##### Relationships and data flows
- Both frontends (web & desktop) → communicate via HTTPS to the Backend API.
- Backend → reads/writes to the PostgreSQL database via Drizzle ORM.
- Backend Cron Services → run recurring jobs (budget calculations, timer notifications) on schedule → update DB or send emails.
- Backend Mail Utility → sends outgoing emails to SMTP provider.
- Docker-Compose → brings up all above containers and sets network links.

##### Architectural patterns and design principles
- Monorepo with clear separation of concerns: each app in its own directory.
- Modular backend: domain folders under src (auth, admin, projects, etc.).
- Use of middleware for global auth guard.
- Declarative DB migrations/seeds (Drizzle).
- Desktop client uses Tauri’s secure Rust bridge for native capabilities.
- Frontends share composables, plugins, layouts, pages (Nuxt conventions).

##### Essential elements to capture
- All three “apps” and how they deploy/run (containers or Tauri bundle).
- API endpoints/modules and middleware flow.
- DB migrations and seeds as part of the backend startup.
- Cron jobs as background services within the backend.
- Interactions with external SMTP/email service.
- Docker-Compose orchestration of containers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker-Compose Orchestration"
        direction TB
        subgraph "Web Dashboard (Container)"
            direction TB
            WD["Web Dashboard\nNuxt 3 + Vue"]:::frontend
            NUXTConfWD["nuxt.config.ts"]:::frontend
            PagesWD["/app/pages"]:::frontend
            ComponentsWD["/app/components"]:::frontend
            ComposablesWD["/app/composables"]:::frontend
            MiddlewareWD["/app/middleware"]:::frontend
            PluginEdenWD["plugins/eden.ts"]:::frontend
        end

        subgraph "Desktop Client (Container)"
            direction TB
            DC["Desktop Client\nNuxt + Tauri"]:::frontend
            NUXTConfDC["nuxt.config.ts"]:::frontend
            PagesDC["/app/pages"]:::frontend
            ComponentsDC["/app/components"]:::frontend
            ComposablesDC["useEden.ts"]:::frontend
            MiddlewareDC["auth.global.ts"]:::frontend
            subgraph "Tauri Host"
                direction TB
                MainRS["main.rs"]:::frontend
                LibRS["lib.rs"]:::frontend
                TauriConf["tauri.conf.json"]:::frontend
            end
        end

        subgraph "Backend API (Container)"
            direction TB
            API["Backend API\nBun + Drizzle"]:::backend
            Entrypoint["index.ts"]:::backend

            subgraph "Domain Modules"
                direction TB
                Auth["auth"]:::backend
                Admin["admin"]:::backend
                Projects["projects"]:::backend
                TimeEntries["time-entries"]:::backend
                TimeTracker["time-tracker"]:::backend
            end

            MiddlewareAPI["authGuard.ts"]:::backend

            subgraph "Cron Services"
                direction TB
                CronBudget["recurringBudgetCron.ts"]:::backend
                CronTimer["timerNotificationCron.ts"]:::backend
            end

            subgraph "Utilities"
                direction TB
                MailUtil["mail.ts"]:::external
                BaseApp["baseApp.ts"]:::backend
                Validators["validators.ts"]:::backend
            end

            subgraph "DB Config & Migrations"
                direction TB
                DrizzleConfig["drizzle.config.ts"]:::backend
                Schema["schema.ts"]:::backend
                Migrate["migrate.ts"]:::backend
                SeedProd["seedProdData.ts"]:::backend
                SeedTest["seedTestData.ts"]:::backend
                SeedUser["seedUser.ts"]:::backend
                Backfill["backfillRates.ts"]:::backend
                ResetDB["reset.ts"]:::backend
            end

            EntrypointScript["entrypoint.sh"]:::backend
        end

        subgraph "Database (Container)"
            direction TB
            PG["PostgreSQL"]:::database
        end
    end

    %% Connections
    WD -->|HTTP/REST| API
    DC -->|HTTP/REST| API
    API -->|SQL via Drizzle ORM| PG
    CronBudget -->|SQL via Drizzle ORM| PG
    CronTimer -->|SQL via Drizzle ORM| PG
    API -->|SMTP| MailUtil

    %% Click Events Web Dashboard
    click NUXTConfWD "https://github.com/ripwords/timesheet/blob/master/apps/dashboard/nuxt.config.ts"
    click PagesWD "https://github.com/ripwords/timesheet/tree/master/apps/dashboard/app/pages/"
    click ComponentsWD "https://github.com/ripwords/timesheet/tree/master/apps/dashboard/app/components/"
    click ComposablesWD "https://github.com/ripwords/timesheet/tree/master/apps/dashboard/app/composables/"
    click MiddlewareWD "https://github.com/ripwords/timesheet/tree/master/apps/dashboard/app/middleware/"
    click PluginEdenWD "https://github.com/ripwords/timesheet/blob/master/apps/dashboard/app/plugins/eden.ts"
    click WD "https://github.com/ripwords/timesheet/tree/master/apps/dashboard"

    %% Click Events Desktop Client
    click NUXTConfDC "https://github.com/ripwords/timesheet/blob/master/apps/desktop/nuxt.config.ts"
    click PagesDC "https://github.com/ripwords/timesheet/tree/master/apps/desktop/app/pages/"
    click ComponentsDC "https://github.com/ripwords/timesheet/tree/master/apps/desktop/app/components/"
    click ComposablesDC "https://github.com/ripwords/timesheet/blob/master/apps/desktop/app/composables/useEden.ts"
    click MiddlewareDC "https://github.com/ripwords/timesheet/blob/master/apps/desktop/app/middleware/auth.global.ts"
    click MainRS "https://github.com/ripwords/timesheet/blob/master/apps/desktop/src-tauri/src/main.rs"
    click LibRS "https://github.com/ripwords/timesheet/blob/master/apps/desktop/src-tauri/src/lib.rs"
    click TauriConf "https://github.com/ripwords/timesheet/blob/master/apps/desktop/src-tauri/tauri.conf.json"
    click DC "https://github.com/ripwords/timesheet/tree/master/apps/desktop"

    %% Click Events Backend API
    click Entrypoint "https://github.com/ripwords/timesheet/blob/master/apps/server/src/index.ts"
    click Auth "https://github.com/ripwords/timesheet/blob/master/apps/server/src/auth/index.ts"
    click Admin "https://github.com/ripwords/timesheet/blob/master/apps/server/src/admin/departments.ts"
    click Projects "https://github.com/ripwords/timesheet/blob/master/apps/server/src/projects/index.ts"
    click TimeEntries "https://github.com/ripwords/timesheet/blob/master/apps/server/src/time-entries/index.ts"
    click TimeTracker "https://github.com/ripwords/timesheet/blob/master/apps/server/src/time-tracker/index.ts"
    click MiddlewareAPI "https://github.com/ripwords/timesheet/blob/master/apps/server/src/middleware/authGuard.ts"
    click CronBudget "https://github.com/ripwords/timesheet/blob/master/apps/server/src/services/recurringBudgetCron.ts"
    click CronTimer "https://github.com/ripwords/timesheet/blob/master/apps/server/src/services/timerNotificationCron.ts"
    click MailUtil "https://github.com/ripwords/timesheet/blob/master/apps/server/utils/mail.ts"
    click BaseApp "https://github.com/ripwords/timesheet/blob/master/apps/server/utils/baseApp.ts"
    click Validators "https://github.com/ripwords/timesheet/blob/master/apps/server/utils/validators.ts"
    click DrizzleConfig "https://github.com/ripwords/timesheet/blob/master/apps/server/drizzle.config.ts"
    click Schema "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/schema.ts"
    click Migrate "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/migrate.ts"
    click SeedProd "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/seedProdData.ts"
    click SeedTest "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/seedTestData.ts"
    click SeedUser "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/seedUser.ts"
    click Backfill "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/backfillRates.ts"
    click ResetDB "https://github.com/ripwords/timesheet/blob/master/apps/server/src/db/reset.ts"
    click EntrypointScript "https://github.com/ripwords/timesheet/blob/master/apps/server/entrypoint.sh"

    %% Click Events Database
    click PG "https://github.com/ripwords/timesheet/tree/master/apps/server/drizzle.meta/"

    %% Styles
    classDef frontend fill:#E3F2FD,stroke:#2196F3,color:#0D47A1
    classDef backend fill:#E8F5E9,stroke:#4CAF50,color:#1B5E20
    classDef database fill:#FFF3E0,stroke:#FB8C00,color:#E65100
    classDef external fill:#F3E5F5,stroke:#9C27B0,color:#4A148C
```
