How joelgrimberg/timesheetz works
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.