# joelgrimberg/timesheetz architecture

> Architecture diagram of the GitHub repository joelgrimberg/timesheetz, 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/joelgrimberg/timesheetz
- Repository: https://github.com/joelgrimberg/timesheetz

## Overview

##### Project Type and Purpose
- Timesheetz is a timesheet management application written in Go. It offers two distinct interfaces:
- A Terminal User Interface (TUI) for direct terminal interactions.
- A REST API for programmatic management via HTTP endpoints.
- The application stores timesheet entries in a Sqlite database and includes additional features like email notifications and PDF print functionality.

##### File Structure
- Top-Level Organization:
- .github: Contains workflow definitions (e.g., go.yml), which inform us about CI/CD practices.
- cmd/timesheet: Houses the main entry point (main.go) for running the application.
- api: Contains the HTTP API implementation:
▪ api/handler: Implements API endpoint handlers.
▪ api/middleware: Provides middleware logic like request tracing.
- internal: Contains the bulk of the application’s business logic split into several packages:
▪ internal/config: Handles application configuration.
▪ internal/db: Manages database interactions (Sqlite).
▪ internal/email: Manages email features, likely integrating external email services.
▪ internal/print: Contains printing/PDF generation functionality.
▪ internal/ui: Implements the Terminal User Interface (TUI) logic and components.
- docs: Provides API documentation and user guides (e.g., keyboard shortcuts).
- Makefile and go.mod: Indicate build system details and dependency management.

##### Key Components
a. User Interfaces:
- Terminal UI (TUI) (internal/ui): Represents direct terminal-based operations.
- REST API Interface (api, cmd): Represents external HTTP endpoints.
b. Application Core:
- Main Executable (cmd/timesheet/main.go) which dispatches between interfaces on startup.
- Configuration Module (internal/config) for managing config parameters.
c. Data Management:
- Database Module (internal/db): Interacts with the Sqlite database storing timesheet entries.
d. Additional Features:
- Email Module (internal/email): Manages notifications or alerts.
- Print Module (internal/print): Handles PDF generation.
e. Middleware:
- API Middleware (api/middleware) such as request tracing to monitor and log API calls.

##### Relationships and Interactions
- The main executable initiates the application by loading configuration settings from internal/config.
- User commands coming through the TUI (internal/ui) or API requests (api/handler) both interact with the core business logic.
- Database interactions occur via the internal/db package, ensuring that both interfaces read/write to the Sqlite database.
- When notifications or prints are necessary, the corresponding modules (internal/email and internal/print) are invoked.
- Middleware (api/middleware) intercepts API calls to provide cross-cutting concerns like tracing.

##### Architectural Patterns and Design Principles
- The application follows a modular approach where functionalities are clearly separated into distinct packages.
- There is a clear separation of concerns — for instance, UI (internal/ui) is entirely separated from data access (internal/db) and external communications (internal/email).
- The REST API architecture is structured in layers: HTTP handlers, middleware, and underlying business logic.
- The TUI encapsulates user interactions and likely employs a guidance pattern using event-driven updates.

##### Relevant Technologies and Frameworks
- Go language is used throughout, with clear dependency management via go.mod and go.sum.
- Sqlite is the chosen database engine.
- A CI/CD pipeline is in place (via .github/workflows/go.yml).
- For email functionality, integration with an external service like Resend is indicated in the README.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interfaces"
        TUI["Terminal UI (internal/ui)"]:::interfaces
        subgraph "REST API"
            APIHandler["API Handler (api/handler)"]:::interfaces
            APIMiddleware["API Middleware (api/middleware)"]:::interfaces
        end
    end

    subgraph "Core Application"
        MainExecutable["Main Executable (cmd/timesheet/main.go)"]:::core
        Config["Configuration Module (internal/config)"]:::core
    end

    subgraph "Data and Services"
        DB["Sqlite Database (internal/db)"]:::services
        Email["Email Module (internal/email)"]:::services
        Print["Print/PDF Module (internal/print)"]:::services
    end

    CI["CI/CD Workflows (.github/workflows)"]:::cicd

    TUI -->|"commands"| MainExecutable
    APIHandler -->|"HTTPrequests"| APIMiddleware
    APIMiddleware -->|"processes"| MainExecutable
    MainExecutable -->|"loadsConfig"| Config
    MainExecutable -->|"CRUDoperations"| DB
    MainExecutable -->|"sendsEmail"| Email
    MainExecutable -->|"generatesPDF"| Print
    CI -.->|"builds"| MainExecutable

    click TUI "https://github.com/joelgrimberg/timesheetz/tree/main/internal/ui"
    click APIHandler "https://github.com/joelgrimberg/timesheetz/blob/main/api/handler/api.go"
    click APIMiddleware "https://github.com/joelgrimberg/timesheetz/blob/main/api/middleware/tracer.go"
    click MainExecutable "https://github.com/joelgrimberg/timesheetz/blob/main/cmd/timesheet/main.go"
    click Config "https://github.com/joelgrimberg/timesheetz/blob/main/internal/config/config.go"
    click DB "https://github.com/joelgrimberg/timesheetz/blob/main/internal/db/db.go"
    click Email "https://github.com/joelgrimberg/timesheetz/blob/main/internal/email/email.go"
    click Print "https://github.com/joelgrimberg/timesheetz/blob/main/internal/print/pdf.go"
    click CI "https://github.com/joelgrimberg/timesheetz/blob/main/.github/workflows/go.yml"

    classDef interfaces fill:#bbf,stroke:#333,stroke-width:2px;
    classDef core fill:#fdd,stroke:#333,stroke-width:2px;
    classDef services fill:#dfd,stroke:#333,stroke-width:2px;
    classDef cicd fill:#fcc,stroke:#333,stroke-width:2px;
```
