# joellebron-analyst/my_codes architecture

> Architecture diagram of the GitHub repository joellebron-analyst/my_codes, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/joellebron-analyst/my_codes
- Repository: https://github.com/joellebron-analyst/my_codes

## Overview

1. **Repository shape**
   - This is a small, script-driven data pipeline rather than a multi-service application.
   - The repository currently appears to contain only a top-level `README.md`, so the architecture is defined by the process described there: one Python script that pulls data, transforms it, and writes Excel reports.

2. **Core purpose**
   - The system automates attendance and exception reporting for employees.
   - It combines three data domains: employee master data, daily attendance logs, and absence/exceptions such as vacations or medical leave.

3. **Primary runtime and libraries**
   - The solution is Python-based.
   - `pandas` and `numpy` are the main data-processing dependencies.
   - Odoo access is via XML-RPC, which makes Odoo the external system of record rather than a local database.

4. **Main external integration boundary: Odoo**
   - The script connects to an Odoo instance at `https://cabicash.odoo.com` using database name, username, and API key.
   - It reads from HR-related models:
     - `hr.employee` for employees
     - `hr.leave` for vacation/exception records
     - `hr.attendance` for clock-in/clock-out data
   - Architecturally, Odoo is the source of truth for operational HR data.

5. **Secondary input boundary: Excel configuration files**
   - The pipeline also depends on local Excel files under two logical folders:
     - `Schedule_change/` for roster/schedule definitions
     - `Schedule_Exception/` for exception calendars and date-based exception rules
   - These files act as business configuration inputs that influence attendance classification.

6. **Processing pipeline**
   - The pipeline is sequential:
     1. Authenticate with Odoo
     2. Extract employees
     3. Extract and clean leave/exception data
     4. Extract attendance records
     5. Normalize time zones and formats
     6. Merge attendance with roster and exception data
     7. Apply business rules
     8. Export final Excel reports
   - This is a classic ETL-style flow with business-rule enrichment in the middle.

7. **Data normalization and transformation layer**
   - A significant part of the architecture is transformation, not just extraction.
   - The script converts UTC timestamps to `America/Santo_Domingo`.
   - It handles null clock-out values, duplicate attendance rows, and time-format normalization.
   - It also translates exception labels into standardized business terms, such as mapping localized vacation/leave names to canonical categories.

8. **Business rules engine**
   - The classification logic is embedded in the script and determines whether an employee is:
     - `Late`
     - `On Time`
     - `Exception`
     - `No Show`
     - `Holiday at Home`
   - The key lateness rule is time-threshold based: clock-in compared with scheduled start time plus a few minutes of tolerance.
   - Exception matching is performed using employee identity data and date range matching.

9. **Schedule/roster dependency**
   - Roster files determine the expected working schedule against which attendance is evaluated.
   - The architecture implies schedule data is externalized rather than hardcoded, which makes schedule changes a configuration concern.
   - Separate roster files for normal days and Saturdays indicate the reporting logic branches by day type.

10. **Special operating modes**
    - There is a “Shift Start” mode used when many clock-out values are missing.
    - This suggests the script has a fallback reporting path when the attendance dataset is incomplete.
    - Holiday handling is another branch point: the same absence/no-show situation is interpreted differently depending on the `is_holiday` parameter.

11. **Outputs**
    - The final product is one or more Excel workbooks, not a database writeback or API response.
    - Report locations include:
      - `Attendance/final_results/Shift_Start.xlsx`
      - `final_results/Attendance/Attendance_Report.xlsx`
    - This makes the system a file-producing batch job.

12. **Operational parameters**
    - The main runtime controls are:
      - `is_holiday`
      - `ingresar_fecha`
    - These parameters indicate the script is designed to process one date at a time, with behavior changing based on whether the target date is a holiday.

13. **Architectural boundary summary**
    - Inputs come from two places: Odoo and local Excel files.
    - Processing happens entirely in Python memory using pandas-style tabular transformations.
    - Outputs are written to Excel for downstream human consumption.
    - There is no evidence of a web UI, persistent application database, or asynchronous job system in the current repository snapshot.

14. **What to diagram**
    - For an accurate architecture diagram, the key components are:
      - Odoo HR system as external data source
      - Local roster/exception Excel files as configuration inputs
      - Python ETL script as the central processor
      - Business rules layer for attendance classification
      - Excel report generation as the final output boundary

Main entry points: [`Attendance_Flow`](https://github.com/joellebron-analyst/my_codes/tree/main/Attendance_Flow) (Attendance Flow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external_inputs["External Inputs"]
  node_odoo_hr[("Odoo HR<br/>external HR source")]
  node_schedule_change["Schedule Files<br/>excel config"]
  node_schedule_exception["Exception Files<br/>excel config"]
end

subgraph group_processing["Processing"]
  node_attendance_flow["Attendance Flow<br/>python ETL"]
  node_auth(("Authenticate<br/>xml-rpc login"))
  node_employee_extract["Employees<br/>extract stage"]
  node_leave_extract["Leaves<br/>extract stage"]
  node_attendance_extract["Attendance<br/>extract stage"]
  node_normalize["Normalize<br/>data transform"]
  node_merge["Merge Inputs<br/>join stage"]
  node_holiday_branch(("Holiday Mode<br/>date branch"))
  node_shift_mode{{"Shift Start<br/>fallback mode"}}
  node_rules{{"Rules Engine<br/>classification logic"}}
  node_statuses["Attendance Statuses<br/>canonical outcomes"]
end

subgraph group_outputs["Outputs"]
  node_report["Excel Reports<br/>file output"]
  node_shift_report["Shift Report<br/>file output"]
end

node_attendance_flow -->|"starts"| node_auth
node_auth -->|"connects"| node_odoo_hr
node_attendance_flow -->|"runs"| node_employee_extract
node_attendance_flow -->|"runs"| node_leave_extract
node_attendance_flow -->|"runs"| node_attendance_extract
node_employee_extract -->|"reads"| node_odoo_hr
node_leave_extract -->|"reads"| node_odoo_hr
node_attendance_extract -->|"reads"| node_odoo_hr
node_attendance_flow -->|"transforms"| node_normalize
node_normalize -->|"uses"| node_schedule_change
node_normalize -->|"uses"| node_schedule_exception
node_attendance_flow -->|"joins"| node_merge
node_merge -->|"branches"| node_holiday_branch
node_merge -->|"branches"| node_shift_mode
node_holiday_branch -->|"feeds"| node_rules
node_shift_mode -->|"feeds"| node_rules
node_schedule_change -.->|"informs"| node_rules
node_schedule_exception -.->|"modifies"| node_rules
node_rules -->|"produces"| node_statuses
node_statuses -->|"writes"| node_report
node_statuses -->|"writes"| node_shift_report

click node_attendance_flow "https://github.com/joellebron-analyst/my_codes/tree/main/Attendance_Flow"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_odoo_hr,node_schedule_change,node_schedule_exception toneBlue
class node_attendance_flow,node_auth,node_employee_extract,node_leave_extract,node_attendance_extract,node_normalize,node_merge,node_holiday_branch,node_shift_mode,node_rules,node_statuses toneAmber
class node_report,node_shift_report toneMint
```

## Components

### External Inputs

Source systems and local configuration files consumed by the pipeline.

- **Odoo HR**: external HR source · System of record for employees, leave, and attendance via XML-RPC.
- **Schedule Files**: excel config · Roster and schedule definitions used to evaluate expected work times.
- **Exception Files**: excel config · Holiday and date-based exception rules that modify attendance outcomes.

### Processing

Python ETL and rule-based attendance classification.

- [Attendance Flow](https://github.com/joellebron-analyst/my_codes/tree/main/Attendance_Flow): python ETL · Single batch script that orchestrates extraction, transformation, and reporting. · `Attendance_Flow`
- **Authenticate**: xml-rpc login · Connects to Odoo using database, username, and API key.
- **Employees**: extract stage · Pulls employee master data used for identity matching.
- **Leaves**: extract stage · Pulls vacation and medical leave records for exception handling.
- **Attendance**: extract stage · Pulls clock-in and clock-out records from Odoo.
- **Normalize**: data transform · Cleans duplicates, null clock-outs, timestamps, time zones, and labels.
- **Merge Inputs**: join stage · Combines attendance with schedules and exception calendars.
- **Holiday Mode**: date branch · Adjusts classification behavior when the target date is a holiday.
- **Shift Start**: fallback mode · Alternative reporting path used when many clock-out values are missing.
- **Rules Engine**: classification logic · Applies lateness, exception, no-show, and holiday-at-home rules.
- **Attendance Statuses**: canonical outcomes · Standard results such as On Time, Late, Exception, No Show, and Holiday at Home.

### Outputs

Excel reports produced for human consumption.

- **Excel Reports**: file output · Final attendance workbooks written as batch outputs.
- **Shift Report**: file output · Fallback workbook generated for shift-start processing.

## Connections

- Attendance Flow → Authenticate: starts · Begins by authenticating against Odoo.
- Authenticate → Odoo HR: connects · Uses XML-RPC to reach the HR system of record.
- Attendance Flow → Employees: runs · Orchestrates extraction of employee records.
- Attendance Flow → Leaves: runs · Orchestrates extraction of leave records.
- Attendance Flow → Attendance: runs · Orchestrates extraction of attendance records.
- Employees → Odoo HR: reads · Pulls employee master data from Odoo.
- Leaves → Odoo HR: reads · Pulls leave and exception records from Odoo.
- Attendance → Odoo HR: reads · Pulls clock-in and clock-out rows from Odoo.
- Attendance Flow → Normalize: transforms · Normalizes raw records before rule evaluation.
- Normalize → Schedule Files: uses · Loads roster definitions and work schedules.
- Normalize → Exception Files: uses · Loads exception calendars and special date rules.
- Attendance Flow → Merge Inputs: joins · Combines cleaned attendance with external configuration.
- Merge Inputs → Holiday Mode: branches · Selects holiday-specific handling when required.
- Merge Inputs → Shift Start: branches · Selects fallback shift-start handling for incomplete attendance.
- Holiday Mode → Rules Engine: feeds · Sends holiday-aware records into classification.
- Shift Start → Rules Engine: feeds · Sends fallback-mode records into classification.
- Schedule Files → Rules Engine: informs · Defines expected start times and day-type schedules.
- Exception Files → Rules Engine: modifies · Changes classification for holidays and exceptions.
- Rules Engine → Attendance Statuses: produces · Assigns attendance outcomes based on business logic.
- Attendance Statuses → Excel Reports: writes · Exports the standard Excel attendance workbook.
- Attendance Statuses → Shift Report: writes · Exports the fallback shift-start workbook when needed.