# aliakbar007/attendance-system-sih25012 architecture

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

- Interactive diagram: https://gitdiagram.com/aliakbar007/attendance-system-sih25012
- Repository: https://github.com/aliakbar007/attendance-system-sih25012

## Overview

1. This is a small, self-contained desktop attendance application, not a client-server system. The architecture is centered on a local GUI, local face/identity data, and file-based persistence.

2. `main_gui_ctk.py` is the primary application entry point and user-facing layer. Based on the name and the problem domain, it is the teacher/operator interface for starting attendance capture, viewing results, and interacting with the system.

3. `util.py` is the shared logic layer. It is the most likely place for attendance rules, face matching or identity lookup, file read/write helpers, and any non-UI processing used by the GUI.

4. The `db/` directory holds serialized application state in pickle files (`hom.pickle`, `oniq.pickle`). These appear to be the persisted identity/recognition data used by the app at runtime, likely representing enrolled users or face feature data.

5. Attendance output is stored in flat files rather than a database:
   - `log.csv` looks like the main attendance/event log.
   - `logged_in.csv` appears to track already-processed or currently present identities to avoid duplicate entries.
   This means the system relies on filesystem state as its primary persistence boundary.

6. The typical data flow is: user opens the GUI → the app invokes utility functions → the utility layer compares captured identity/face input against the serialized database in `db/` → if a match is found, attendance is recorded in CSV files → the GUI shows the result to the operator.

7. The repo does not show any network service, API layer, or external database server. That makes the operational boundary entirely local: one machine runs the UI and processing, while all state lives in the repository’s files.

8. `test.py` and `testing.py` are separate validation/support scripts, likely used to exercise recognition or attendance logic without using the full GUI. They are not part of the main runtime path but help verify behavior.

9. `requirements.txt` defines the runtime dependencies, which likely include the GUI toolkit and any computer-vision or data-processing libraries needed by `main_gui_ctk.py` and `util.py`. Those dependencies materially affect the architecture because this is a desktop, dependency-heavy local app.

10. For an architecture diagram, the main boundaries to draw are:
   - Operator/UI boundary: `main_gui_ctk.py`
   - Business logic boundary: `util.py`
   - Persistent identity store: `db/*.pickle`
   - Attendance record store: `log.csv` and `logged_in.csv`
   - Supporting test scripts: `test.py`, `testing.py`

11. The main architectural characteristic is that state is file-backed and tightly coupled to the desktop app. That keeps deployment simple for rural-school usage, but it also means data integrity and concurrency are managed at the application/file level rather than by a database or service layer.

Main entry points: [`util.py`](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py) (Utilities), [`main_gui_ctk.py`](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py) (Main GUI), [`db`](https://github.com/aliakbar007/attendance-system-sih25012/tree/main/db) (Identity Store), [`log.csv`](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/log.csv) (Attendance Log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User Interface"]
  node_main_gui["Main GUI<br/>desktop entrypoint<br/>[main_gui_ctk.py]"]
  node_gui_flow["Screen Flow<br/>ui orchestration<br/>[main_gui_ctk.py]"]
  node_capture["Capture Input<br/>camera/input<br/>[main_gui_ctk.py]"]
  node_result_view["Attendance View<br/>ui output<br/>[main_gui_ctk.py]"]
end

subgraph group_logic["Core Logic"]
  node_util["Utilities<br/>shared logic<br/>[util.py]"]
  node_match_rules["Match Rules<br/>identity logic<br/>[util.py]"]
  node_attendance_write["Record Attendance<br/>write logic<br/>[util.py]"]
  node_file_helpers["File Helpers<br/>io helpers<br/>[util.py]"]
end

subgraph group_storage["File State"]
  node_identity_store[("Identity Store<br/>pickle data")]
  node_hom_data["hom.pickle<br/>enrollment data<br/>[hom.pickle]"]
  node_oniq_data["oniq.pickle<br/>enrollment data<br/>[oniq.pickle]"]
  node_attendance_log["Attendance Log<br/>csv ledger<br/>[log.csv]"]
  node_logged_state["Logged State<br/>csv state<br/>[logged_in.csv]"]
end

subgraph group_support["Support"]
  node_tests["Validation Scripts<br/>[test.py]"]
  node_testing["Testing Script<br/>[testing.py]"]
  node_requirements["Dependencies<br/>package spec<br/>[requirements.txt]"]
end

node_main_gui -->|"drives"| node_gui_flow
node_main_gui -->|"starts"| node_capture
node_main_gui -->|"shows"| node_result_view
node_gui_flow -->|"uses"| node_util
node_capture -->|"sends data"| node_util
node_util -->|"applies"| node_match_rules
node_util -->|"records"| node_attendance_write
node_util -->|"reads/writes"| node_file_helpers
node_match_rules -->|"reads"| node_identity_store
node_identity_store -->|"contains"| node_hom_data
node_identity_store -->|"contains"| node_oniq_data
node_attendance_write -->|"appends"| node_attendance_log
node_attendance_write -->|"updates"| node_logged_state
node_file_helpers -->|"accesses"| node_attendance_log
node_file_helpers -->|"accesses"| node_logged_state
node_tests -.->|"exercises"| node_util
node_testing -.->|"exercises"| node_util
node_main_gui -.->|"depends on"| node_requirements
node_util -.->|"depends on"| node_requirements

click node_main_gui "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py"
click node_gui_flow "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py"
click node_capture "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py"
click node_result_view "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py"
click node_util "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py"
click node_match_rules "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py"
click node_attendance_write "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py"
click node_file_helpers "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py"
click node_identity_store "https://github.com/aliakbar007/attendance-system-sih25012/tree/main/db"
click node_hom_data "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/db/hom.pickle"
click node_oniq_data "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/db/oniq.pickle"
click node_attendance_log "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/log.csv"
click node_logged_state "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/logged_in.csv"
click node_tests "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/test.py"
click node_testing "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/testing.py"
click node_requirements "https://github.com/aliakbar007/attendance-system-sih25012/blob/main/requirements.txt"

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_main_gui,node_gui_flow,node_capture,node_result_view toneBlue
class node_util,node_match_rules,node_attendance_write,node_file_helpers toneAmber
class node_identity_store,node_hom_data,node_oniq_data,node_attendance_log,node_logged_state toneMint
class node_tests,node_testing,node_requirements toneRose
```

## Components

### User Interface

Operator-facing desktop entry point and interaction layer.

- [Main GUI](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py): desktop entrypoint · Primary operator interface for running attendance capture and viewing results. · `main_gui_ctk.py`
- [Screen Flow](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py): ui orchestration · Coordinates capture actions, status updates, and operator feedback. · `main_gui_ctk.py`
- [Capture Input](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py): camera/input · User-triggered capture path that feeds identity or face data into processing. · `main_gui_ctk.py`
- [Attendance View](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/main_gui_ctk.py): ui output · Displays recognition and attendance outcomes to the operator. · `main_gui_ctk.py`

### Core Logic

Shared processing and attendance rules.

- [Utilities](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py): shared logic · Common rules and processing used by the GUI for matching and file handling. · `util.py`
- [Match Rules](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py): identity logic · Compares captured identity or face data against enrolled records. · `util.py`
- [Record Attendance](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py): write logic · Appends attendance outcomes and prevents duplicate entries. · `util.py`
- [File Helpers](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/util.py): io helpers · Shared read/write helpers for local CSV and pickle-backed state. · `util.py`

### File State

Local persisted identity data and attendance records.

- [Identity Store](https://github.com/aliakbar007/attendance-system-sih25012/tree/main/db): pickle data · Serialized recognition or enrollment data used at runtime. · `db`
- [hom.pickle](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/db/hom.pickle): enrollment data · One persisted identity or feature dataset used by matching logic. · `db/hom.pickle`
- [oniq.pickle](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/db/oniq.pickle): enrollment data · Another persisted identity or feature dataset used by matching logic. · `db/oniq.pickle`
- [Attendance Log](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/log.csv): csv ledger · Main flat-file log of attendance events. · `log.csv`
- [Logged State](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/logged_in.csv): csv state · Tracks already-processed or present identities to avoid duplicates. · `logged_in.csv`

### Support

Non-runtime validation and dependency definition.

- [Validation Scripts](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/test.py): scripts · Standalone scripts used to exercise recognition and attendance logic. · `test.py`
- [Testing Script](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/testing.py): script · Additional support script for verifying behavior outside the GUI. · `testing.py`
- [Dependencies](https://github.com/aliakbar007/attendance-system-sih25012/blob/main/requirements.txt): package spec · Runtime dependencies for the GUI and processing stack. · `requirements.txt`

## Connections

- Main GUI → Screen Flow: drives · The entry point coordinates the operator workflow.
- Main GUI → Capture Input: starts · The GUI initiates attendance capture actions.
- Main GUI → Attendance View: shows · The GUI presents recognition and attendance results.
- Screen Flow → Utilities: uses · Screen actions delegate processing to shared logic.
- Capture Input → Utilities: sends data · Captured input is handed to utility processing.
- Utilities → Match Rules: applies · Utility code performs matching and identity lookup.
- Utilities → Record Attendance: records · Utility code writes attendance outcomes and guards duplicates.
- Utilities → File Helpers: reads/writes · Utility code uses shared file access helpers.
- Match Rules → Identity Store: reads · Matching logic loads enrolled identity data from pickle files.
- Identity Store → hom.pickle: contains · Identity store includes the hom dataset.
- Identity Store → oniq.pickle: contains · Identity store includes the oniq dataset.
- Record Attendance → Attendance Log: appends · Attendance events are written to the main CSV log.
- Record Attendance → Logged State: updates · Duplicate-prevention state is maintained in a CSV file.
- File Helpers → Attendance Log: accesses · Shared helpers support reading and writing the log file.
- File Helpers → Logged State: accesses · Shared helpers support reading and writing logged-in state.
- Validation Scripts → Utilities: exercises · Validation scripts likely call shared processing directly.
- Testing Script → Utilities: exercises · Additional script for non-GUI verification.
- Main GUI → Dependencies: depends on · The desktop app relies on declared runtime packages.
- Utilities → Dependencies: depends on · Shared logic likely requires the same processing libraries.