LightTAM/docs/DETAILED_OVERVIEW.MD

LightTAM: Detailed Overview

LightTAM (Lightweight Time And Attendance Manager) is a terminal-based application for managing employee or student attendance using RFID cards. The system is modular, with each component responsible for a specific aspect of the program's functionality. Below is a detailed overview of how the program works, referencing the component UML diagram (component_uml.png).

Component Overview

1. Main Application (main.c)

• Role: Entry point of the program. Initializes all subsystems, parses command-line arguments, loads the user database, and starts the main event loop.
• Responsibilities:
  • Initializes the logger, file/database handlers, and TUI.
  • Loads user data from the specified file.
  • Handles program shutdown and resource cleanup.

2. Terminal User Interface (TUI) (tui.c, tui.h)

• Role: Provides all user interaction via a terminal-based UI using ncurses.
• Responsibilities:
  • Displays menus (main, edit, search, user details, etc.).
  • Handles keyboard input and navigation.
  • Calls business logic functions based on user actions.
  • Shows dialogs for success, warnings, and errors.
  • Manages forms for adding/removing users and logging time events.

3. User Management (users.c, users.h)

• Role: Manages the in-memory linked list of users.
• Responsibilities:
  • Defines the person_t, node_t, and list_t structures.
  • Provides functions to add, remove, search, and update users.
  • Handles synchronization (mutex) for thread safety.
  • Calculates presence times and manages user states.

4. File Handler (file_handler.c, file_handler.h)

• Role: Handles reading and writing user data to CSV files.
• Responsibilities:
  • Loads the user list from a CSV file at startup.
  • Saves the user list to a CSV file on demand.
  • Exports user or database information to external files.

5. RFID Handler (rfid_handler.c, rfid_handler.h)

• Role: Interfaces with the RFID reader hardware via a serial port.
• Responsibilities:
  • Opens and manages the serial port connection.
  • Reads RFID card data and matches it to users.
  • Triggers time event logging when a card is detected.

6. Logger (logger.c, logger.h)

• Role: Logs all actions, errors, and system events to a journal file.
• Responsibilities:
  • Provides logging functions for other modules.
  • Records user actions, errors, and system messages for auditing.

7. Utilities (utils.h)

• Role: Provides helper functions used throughout the program.
• Responsibilities:
  • String manipulation, time formatting, and other common tasks.

Component Interactions

• TUI ↔ User Management: TUI calls user management functions to modify or query the user list.
• TUI ↔ File Handler: TUI triggers file operations for loading, saving, and exporting data.
• TUI ↔ RFID Handler: TUI may display status or prompt for RFID actions.
• RFID Handler ↔ User Management: When a card is read, the handler updates the user list.
• All Components ↔ Logger: All modules log actions and errors via the logger.

Error Handling & Logging

• All errors (file I/O, serial port, invalid input) are reported to the user via TUI dialogs and logged in the journal file.
• The logger ensures traceability for all critical operations.

Extensibility

• The modular design allows for easy extension, such as supporting new file formats, additional authentication methods, or a graphical UI.

---

For further details, see the README.md and the code documentation in each header file.