How joellebron-analyst/my_codes works
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 Attendance Flow
Components 16
External Inputs
Source systems and local configuration files consumed by the pipeline.
- Odoo HR · System of record for employees, leave, and attendance via XML-RPC.
- Schedule Files · Roster and schedule definitions used to evaluate expected work times.
- Exception Files · Holiday and date-based exception rules that modify attendance outcomes.
Processing
Python ETL and rule-based attendance classification.
- Attendance Flow · Single batch script that orchestrates extraction, transformation, and reporting.
Attendance_Flow - Authenticate · Connects to Odoo using database, username, and API key.
- Employees · Pulls employee master data used for identity matching.
- Leaves · Pulls vacation and medical leave records for exception handling.
- Attendance · Pulls clock-in and clock-out records from Odoo.
- Normalize · Cleans duplicates, null clock-outs, timestamps, time zones, and labels.
- Merge Inputs · Combines attendance with schedules and exception calendars.
- Holiday Mode · Adjusts classification behavior when the target date is a holiday.
- Shift Start · Alternative reporting path used when many clock-out values are missing.
- Rules Engine · Applies lateness, exception, no-show, and holiday-at-home rules.
- Attendance Statuses · Standard results such as On Time, Late, Exception, No Show, and Holiday at Home.
Outputs
Excel reports produced for human consumption.
- Excel Reports · Final attendance workbooks written as batch outputs.
- Shift Report · Fallback workbook generated for shift-start processing.
Connections 21
- 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.