# sahvsergio/treehouse_time_tracking_app architecture

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

- Interactive diagram: https://gitdiagram.com/sahvsergio/treehouse_time_tracking_app
- Repository: https://github.com/sahvsergio/treehouse_time_tracking_app

## Overview

##### Project type and purpose
- This is a small, command-line, CSV-backed “Time Tracker” utility written in Python.
- Its primary purpose is to let a user start/stop timing work on client projects and to query totals (all‐time, date‐range, last X days) by reading and appending entries in a CSV file.

##### File structure
- README.md                – project description and mission
- data.csv                 – persistent store of time-tracking records
- main.py                  – application entry point; sets up environment and kicks off the menu
- menus.py                 – user interaction layer; text menus, prompts, input validation
- functions.py             – core business logic: start_tracking, stop_tracking, display totals, filtering
- utils.py                 – shared helpers (e.g., parsing dates, formatting output)

##### Extract key architectural insights
- It’s a simple modular CLI tool (not client/server or web-based).
- Logic is separated into two main layers:
a. Presentation/Menu layer (menus.py)
b. Business logic layer (functions.py + utils.py)
- Persistence is flat-file (data.csv) with CSV read/write operations.
- External dependency: dateutil for robust datetime parsing.

##### Components
a. CLI Interface
– main.py: bootstraps the app
– menus.py: displays menus, captures user choices
b. Business Logic
– functions.py: contains all time-tracking functions (start/stop, display totals, filters)
c. Utilities
– utils.py: date parsing, formatting, any shared helpers
d. Data Store
– data.csv: append/read operations; represents persistent time records
e. External Library
– python-dateutil: for parsing user-entered date strings and “now” timestamps

##### Relationships and data flow
- User → main.py
↓
- menus.py (prompt user, collect parameters)
↓
- functions.py (invoke start/stop/display logic)
↔
- utils.py (date parsing/formatting helpers)
↔
- data.csv (read existing records, append new entries)
- functions.py uses dateutil to interpret timestamps

##### Architectural patterns and principles
- Layered modularization:
- Presentation (menus.py)
- Application logic (functions.py)
- Utilities (utils.py)
- Data persistence (CSV file)
- Single Responsibility: each module focuses on one aspect (UI vs. logic vs. utils).
- Dependency on external library limited to datetime parsing.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User
    User["User"]:::external
    %% Presentation Layer
    Main["main.py: Application Entry Point"]:::presentation
    Menus["menus.py: Presentation/Menu Layer"]:::presentation
    %% Business Logic
    Functions["functions.py: Business Logic"]:::business
    %% Utilities
    Utils["utils.py: Utilities"]:::utilities
    %% Data Store
    DataCSV["data.csv: Persistent CSV Store"]:::datastore
    %% External Library
    DateUtil["python-dateutil"]:::external

    %% Flow
    User -->|start app| Main
    Main -->|display menus| Menus
    Menus -->|invoke logic| Functions
    Functions -->|helper calls| Utils
    Utils -->|formatted dates| Functions
    Functions -->|read/write records| DataCSV
    Functions -->|parse timestamps| DateUtil

    %% Click Events
    click Main "https://github.com/sahvsergio/treehouse_time_tracking_app/blob/main/main.py"
    click Menus "https://github.com/sahvsergio/treehouse_time_tracking_app/blob/main/menus.py"
    click Functions "https://github.com/sahvsergio/treehouse_time_tracking_app/blob/main/functions.py"
    click Utils "https://github.com/sahvsergio/treehouse_time_tracking_app/blob/main/utils.py"
    click DataCSV "https://github.com/sahvsergio/treehouse_time_tracking_app/blob/main/data.csv"

    %% Styles
    classDef presentation fill:#FFD580,stroke:#333,stroke-width:1px;
    classDef business fill:#A0C4FF,stroke:#333,stroke-width:1px;
    classDef utilities fill:#BDB2FF,stroke:#333,stroke-width:1px;
    classDef datastore fill:#C1FBA4,stroke:#333,stroke-width:1px;
    classDef external fill:#FFADAD,stroke:#333,stroke-width:1px;
```
