# sahvsergio/treehouse_birthday_app architecture

> Architecture diagram of the GitHub repository sahvsergio/treehouse_birthday_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_birthday_app
- Repository: https://github.com/sahvsergio/treehouse_birthday_app

## Overview

##### Project type and purpose
- This is a console‐based, open‐source Python CLI “Birthday App” that reads a CSV file of birthdays and presents a simple interactive menu. Its main responsibilities are:
- Loading and parsing `birthdays.csv`
- Converting date strings to datetime objects (using `python-dateutil`)
- Calculating ages, upcoming birthdays, and age differences
- Rendering menus and routing user choices

##### File structure
- Top‐level scripts:
- `main.py` – application entry point; initializes the menu loop
- `menus.py` – displays options and captures user input
- `functions.py` – core business logic (age computations, filtering upcoming birthdays)
- `utils.py` – shared helpers (e.g. pluralization)
- Data file: `birthdays.csv` – source of record data
- Virtual env: `env/` – isolation of dependencies (e.g. `python-dateutil`, `pycodestyle`, `pip`)
- Configuration: `requirements.txt` – lists Python dependencies

##### README for architectural insights
- The README spells out the three functions to implement:
1. `display_age()`
2. `display_age_differences()`
3. `upcoming_birthdays()`
- Suggests helper functions for date‐parsing and age calculation, pointing to reuse and separation of concerns.

##### Main components
a. CLI Layer
- Modules: `main.py`, `menus.py`
- Responsibilities: user I/O, menu navigation, invoking business logic
b. Business Logic Layer
- Module: `functions.py`
- Responsibilities: age computations, upcoming birthday filtering, difference calculations
c. Utilities Layer
- Module: `utils.py`
- Responsibilities: generic helper routines (pluralization, formatting)
d. Data Layer
- File: `birthdays.csv`
- Responsibilities: persistent storage of person records (name, date)
e. External Dependency
- Library: `python-dateutil`
- Responsibilities: robust date parsing and manipulation

##### Relationships and interactions
- User issues input → `main.py` calls → `menus.py`
- `menus.py` routes to an option handler in `functions.py`
- `functions.py` calls:
- A parser helper in `functions.py` or `utils.py` → uses `python-dateutil` to convert strings → datetime object
- Age or upcoming filter routines → produces results
- Results passed back up to `menus.py` → printed via `main.py`

##### Architectural patterns and principles
- Separation of Concerns:
- I/O (CLI) vs. Business Logic vs. Utilities vs. Data
- Single Responsibility: each module holds its own domain logic
- Reusability: helper functions for parsing and pluralization
- Dependency Isolation: external libs confined to functions that need them

##### Details to capture
- File relationships: which module imports which
- Data transformations: raw CSV string → datetime → calculations
- Menu routing: how user choice maps to function calls
- Extension paths: where new features plug in

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Entity
    User["User"]:::user

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Main["main.py"]:::cli
        CLI_Menus["menus.py"]:::cli
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        BL_Functions["functions.py"]:::logic
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        Utils["utils.py"]:::utils
    end

    %% Data Layer
    subgraph "Data Layer"
        Data_File["birthdays.csv"]:::data
    end

    %% External Dependency
    subgraph "External Dependency"
        Ext_DateUtil["python-dateutil"]:::external
        Req["requirements.txt"]:::external
    end

    %% Flow of control and data
    User -->|issues input| CLI_Main
    CLI_Main -->|invokes menu| CLI_Menus
    CLI_Menus -->|routes to handler| BL_Functions
    BL_Functions -->|uses helper| Utils
    BL_Functions -->|parses dates via| Ext_DateUtil
    BL_Functions -->|reads data| Data_File
    BL_Functions -->|reads deps| Req
    CLI_Menus -->|returns results| CLI_Main
    CLI_Main -->|outputs to| User

    %% Click Events
    click CLI_Main "https://github.com/sahvsergio/treehouse_birthday_app/blob/main/main.py"
    click CLI_Menus "https://github.com/sahvsergio/treehouse_birthday_app/blob/main/menus.py"
    click BL_Functions "https://github.com/sahvsergio/treehouse_birthday_app/blob/main/functions.py"
    click Utils "https://github.com/sahvsergio/treehouse_birthday_app/blob/main/utils.py"
    click Data_File "https://github.com/sahvsergio/treehouse_birthday_app/blob/main/birthdays.csv"
    click Ext_DateUtil "https://github.com/sahvsergio/treehouse_birthday_app/tree/main/env/lib/python3.12/site-packages/dateutil"
    click Req "https://github.com/sahvsergio/treehouse_birthday_app/blob/main/requirements.txt"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#004080,color:#000;
    classDef logic fill:#D6FFE0,stroke:#006600,color:#000;
    classDef utils fill:#FFF5A8,stroke:#8C6B00,color:#000;
    classDef data fill:#FFD8A8,stroke:#804000,color:#000,shape:cylinder;
    classDef external fill:#E8D0FF,stroke:#4B0082,color:#000,shape:cloud;
    classDef user fill:#CCCCCC,stroke:#888888,color:#000;
    class User user
```
