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.
• Key Functions:
  • main – program entry, initialization, TUI start, graceful shutdown.
  • handle_sigint – signal handler for program termination.
  • Calls to initialize logger (initLogger), load users (loadListFromCSV), start RFID thread (uartListener).

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

• Role: Provides all user interaction via a terminal-based UI using ncurses.
• Key Functions:
  • mainMenu – main menu display and navigation.
  • personListing – list all users.
  • personSearch – search users by name or UUID.
  • personInfo – show detailed user info.
  • editDatabaseMenu – add, remove, or edit users.
  • dialogWindow – show dialogs (errors, warnings, confirmations).
  • exportDialog – export user or database data.
  • Keyboard input handling, navigation, and forms.

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

• Role: Manages the in-memory linked list of users.
• Key Functions and Structures:
  • person_t, node_t, list_t – data structures for users and the list.
  • addPersonToList – add a user.
  • removePersonFromList – remove a user.
  • findPersonByUUID, findPersonByName – search for users.
  • updatePerson – update user data.
  • calculatePresenceTime – compute attendance.
  • Synchronization using mutex (pthread_mutex_t).

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

• Role: Handles reading and writing user data to CSV files.
• Key Functions:
  • loadListFromCSV – load user list from file.
  • saveListToCSV – save user list to file.
  • exportPersonInfo – export a user's data to an external file.

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

• Role: Interfaces with the RFID reader hardware via a serial port.
• Key Functions:
  • uartListener – thread for reading data from the serial port.
  • processRFIDEvent – process a detected RFID card.
  • sendPacketToDevice – send data to the device.
  • CRC check, card-to-user matching, attendance event logging.

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

• Role: Logs all actions, errors, and system events to a journal file.
• Key Functions:
  • initLogger – initialize the logger.
  • logErrorEvent – log errors.
  • logWarningEvent – log warnings.
  • logHardwareEvent – log hardware events (e.g., RFID).
  • logInfoEvent – log general information.
  • endLogger – close the log file.

7. Utilities (utils.c,utils.h)

• Role: Provides helper functions used throughout the program.
• Key Functions:
  • printDateAndTimeInString – time formatting.
  • String manipulation, input validation, type conversions.

---

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.

---