# alqasmii/library-management- architecture

> Architecture diagram of the GitHub repository alqasmii/library-management-, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alqasmii/library-management-
- Repository: https://github.com/alqasmii/library-management-

## Overview

##### Project type and purpose
- This is a standalone Odoo v15+ module named baramej_library_system (packaged under custom/custom/baramej_library_system).
- It implements a full-stack Library Management System: Python-based business logic (models, cron jobs), XML/QWeb-based UI, JS widget for barcode scanning, scheduled actions for overdue detection and email reminders, and PostgreSQL for persistence.

##### Architectural overview
- At the highest level the system comprises:
a. The Odoo application server (Python runtime, web server, cron scheduler)
b. The PostgreSQL database
c. External integrations: USB barcode scanner (keyboard-wedge), SMTP mail server
d. The custom module code (models, views, data, security, static assets, tests)
- It follows the classic MVC/MVT pattern:
- Models: Python files under models/ (map to DB tables via Odoo ORM)
- Views/Templates: XML files under views/ and QWeb templates (rendered as web pages)
- Controller/UI logic: JS widget (barcode_scanner.js) for client-side interactions
- Cron jobs & data files: scheduled actions & demo data under data/ and demo/
- Security layer: access control under security/

##### Main components
- Frontend layer:
- Web browser / Odoo web client
- QWeb/XML views (CRUD screens, dashboard)
- JavaScript widget (barcode_scanner.js)
- Backend layer:
- Odoo server (Python)
– Models: library_member.py, library_book.py, library_borrow.py, etc.
– Wizards: library_barcode_scan.py
– Cron scheduler: overdue detection, email reminders (ir_cron.xml)
– Business rules & computed fields (limits, fines)
– Security engine (record rules & groups)
- Persistence layer:
- PostgreSQL database (tables for members, books, loans, categories…)
- External services:
- SMTP mail server (email reminders)
- USB barcode scanner (keyboard-wedge input into JS widget)
- Auxiliary:
- demo data loader
- translation files (i18n/en.po)
- tests suite (unittest-based test files)

##### Relationships and data flow
- User → Browser → QWeb/XML view
→ HTTP request to Odoo server → Model methods via ORM → DB → returns data → rendered in view
- Barcode scan: user scans into JS widget → widget sends RPC to Odoo wizard → creates/up-dates library.borrow record
- Cron jobs: Odoo scheduler invokes Python methods on library.borrow → updates overdue flags → triggers mail templates → SMTP server
- Security: Web request passes through record rules & ir.model.access filters based on user group
- Dashboard: server aggregates data (graph/pivot views) → QWeb renders charts

##### Architectural patterns and design principles
- MVC/MVT separation: models vs views vs client-side widget vs data vs security
- Modular design: single Odoo module with clear subdirectories (models, views, data, security, static, tests)
- Event-driven tasks: Odoo cron jobs for overdue detection & reminders
- Layered security: model-level access, record rules, user roles/groups
- Extensibility via standard Odoo API (data files, XML hooks, Python inheritance)

##### Technologies and frameworks
- Backend: Odoo 15+ framework, Python 3.8+, Odoo ORM, ir.cron scheduler
- Frontend: QWeb/XML views, Owl.js (Odoo native), JavaScript barcode widget
- Database: PostgreSQL 12+
- Email: Odoo mail module (SMTP integration)
- Testing: Odoo TestCase (unittest), GitHub Actions CI

##### Detail level
- Don’t overload with every single XML file; group by function (Views vs Data vs Security)
- Explicitly call out key models and workflows (Borrow → Overdue → Reminder)
- Essential modules and patterns, avoiding too much low-level detail

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        Browser["Web Client (Browser)"]:::frontend
        Views["QWeb/XML Views"]:::frontend
        JSWidget["JS Barcode Widget"]:::frontend
    end

    %% Backend/Odoo Server
    subgraph "Backend/Odoo Server"
        subgraph "Models"
            LM["LibraryMember"]:::models
            LB["LibraryBook"]:::models
            LBo["LibraryBorrow"]:::models
            LC["LibraryCategory"]:::models
            LA["LibraryAuthor"]:::models
            LP["LibraryPublisher"]:::models
            LL["LibraryLocation"]:::models
            LE["LibraryEvent"]:::models
            LR["LibraryReservation"]:::models
            LRev["LibraryReview"]:::models
            LSf["LibraryStaff"]:::models
            LMT["LibraryMemberType"]:::models
        end
        Wizards["Barcode Scan Wizard"]:::backend
        Cron["Cron Scheduler"]:::backend
        Templates["Email Templates"]:::backend
        Security["Security Engine"]:::backend
        DataLoader["Data & Demo Loader"]:::backend
    end

    %% Persistence Layer
    DB["PostgreSQL Database"]:::database

    %% External Services
    subgraph "External Services"
        SMTP["SMTP Mail Server"]:::external
        Scanner["USB Barcode Scanner"]:::external
    end

    %% Data Flows
    Browser -->|HTTP request| Views
    Views -->|renders| Browser
    Browser -->|loads widget| JSWidget
    Scanner -->|input| JSWidget
    JSWidget -->|RPC call| Wizards
    Wizards -->|create/update record| LBo
    Views -->|HTTP API| LM
    LM -->|SQL query| DB
    LB -->|SQL query| DB
    LBo -->|SQL query| DB
    LC -->|SQL query| DB
    LA -->|SQL query| DB
    LP -->|SQL query| DB
    LL -->|SQL query| DB
    LE -->|SQL query| DB
    LR -->|SQL query| DB
    LRev -->|SQL query| DB
    LSf -->|SQL query| DB
    LMT -->|SQL query| DB
    Cron -->|cron trigger| LBo
    Cron -->|uses| Templates
    Templates -->|email send| SMTP

    %% Model Relationships
    LM -->|"1..* borrows"| LBo
    LBo -->|"*..1 book"| LB

    %% Click Events
    click Views "https://github.com/alqasmii/library-management-/tree/main/custom/custom/baramej_library_system/views"
    click JSWidget "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/static/src/js/barcode_scanner.js"
    click LM "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_member.py"
    click LB "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_book.py"
    click LBo "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_borrow.py"
    click LC "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_category.py"
    click LA "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_author.py"
    click LP "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_publisher.py"
    click LL "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_location.py"
    click LE "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_event.py"
    click LR "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_reservation.py"
    click LRev "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_review.py"
    click LSf "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_staff.py"
    click LMT "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_member_type.py"
    click Wizards "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/models/library_barcode_scan.py"
    click Cron "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/data/ir_cron.xml"
    click Templates "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/data/mail_templates.xml"
    click Security "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/security/ir.model.access.csv"
    click DataLoader "https://github.com/alqasmii/library-management-/blob/main/custom/custom/baramej_library_system/data/library_member_type_data.xml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064,color:#006064;
    classDef backend fill:#BBDEFB,stroke:#0D47A1,color:#0D47A1;
    classDef models fill:#C5E1A5,stroke:#33691E,color:#33691E;
    classDef database fill:#C8E6C9,stroke:#1B5E20,color:#1B5E20,shape:cylinder;
    classDef external fill:#CFD8DC,stroke:#455A64,color:#455A64;
```
