# younes-el-kadmiri/booksmart architecture

> Architecture diagram of the GitHub repository younes-el-kadmiri/booksmart, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/younes-el-kadmiri/booksmart
- Repository: https://github.com/younes-el-kadmiri/booksmart

## Overview

##### Project Type and Purpose
- This is a monolithic, full-stack web application (a library management & recommendation system) built in Python, using FastAPI as the web framework.
- It exposes both HTML pages (via Jinja2 templates + static assets) and JSON APIs (via FastAPI routers).
- It integrates:
- A relational database (SQLite) accessed through ORM models
- Business logic layer (services) for library operations (adherent, emprunt, réservation, statistiques)
- An ML recommendation engine (TF-IDF model, similarity matrix)
- A web scraper (OpenLibrary, BooksToScrape) for populating the catalog
- Utility modules (email notifications, security, configuration)

##### File-Structure Analysis
- app/main.py: FastAPI application entry point
- app/routers: “Controller” layer – defines HTTP endpoints (auth, adherents, livres, emprunts, recommandations, etc.)
- app/schemas: Pydantic models for request/response validation
- app/models: ORM definitions (tables: utilisateur, livre, emprunt, historique, etc.)
- app/services: Business-logic layer orchestrating data access, ML, emailing, scraping
- app/database.py: Database connection/session management
- app/ml: Recommendation subsystem (TF-IDF, similarity, recommender)
- app/scraping: Scraper scripts for external sources
- app/utils: Cross-cutting concerns (security helpers, email service, config loader)
- static/, templates/: Client-side assets and server-rendered HTML
- data/: Raw/clean CSVs and stored recommendation artifacts
- library.db: SQLite file
- run.sh: Startup script
- requirements.txt: Dependencies

##### System Components
a. Clients & Interfaces
– Web Browser (HTML + CSS + JS)
– External Scheduler/CLI (run.sh for scraping or ML tasks)
b. Web Tier
– FastAPI App (app/main.py)
– Routers (REST & page routes)
– Jinja2 Template Engine
– Static File Server
c. Business Logic
– Service Layer (auth_service, livre_service, etc.)
d. Data Layer
– ORM Models + SQLAlchemy or equivalent
– SQLite Database (library.db)
e. ML Subsystem
– TF-IDF Model, similarity matrix, recommender module
– Pre-trained artifacts (model.pkl, similarity_matrix.pkl)
f. Scraping Subsystem
– Scrapers (openlibrary_scraper, scrap_books_toscrape)
– Scraping Service to orchestrate scraping → data cleaning → DB
g. Utilities & External Services
– Email Service (SMTP)
– Security utils (JWT, hashing)
– Configuration Loader (.env)
– External APIs (OpenLibrary, BooksToScrape)

##### Relationships & Interactions
1. User → Browser → HTTP request
2. FastAPI App
- Routes request to appropriate Router
- Router calls Service layer
- Service invokes Model (DB) or calls ML / Scraping modules
- Service assembles response schema
- Response: JSON or rendered HTML template
3. Scraping & ML tasks
- run.sh or scheduled job triggers scraper
- Scraper populates raw CSV → cleaning → DB
- ML pipeline reads DB or CSV → regenerates model.pkl / similarity_matrix.pkl
- Artifacts stored under data/ or app/ml
4. Email notifications
- Certain services call Email Service utility to send emails (e.g., reservation reminders)

##### Architectural Patterns & Principles
- Layered architecture (Presentation → API → Services → Data)
- Separation of concerns (routers vs. services vs. models vs. utilities)
- Reuse of ML & scraping as distinct subsystems
- Configuration management via .env and config modules
- Pydantic schemas for validation and serialization

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Interfaces"
        Browser["Web Browser"]:::external
        Scheduler["Scheduler / CLI (run.sh)"]:::external
    end

    %% Web Tier
    subgraph "Web Tier" 
        FastAPIApp["FastAPI App"]:::presentation
        Routers["HTTP Routers"]:::presentation
        Templates["Jinja2 Templates"]:::presentation
        Static["Static File Server"]:::presentation
    end

    %% Service Layer
    subgraph "Business Logic Layer"
        Services["Service Layer"]:::business
    end

    %% Data Layer
    subgraph "Data Layer"
        ORM["ORM Models"]:::data
        Database["SQLite Database"]:::data
    end

    %% ML Subsystem
    subgraph "ML Subsystem"
        TFIDF["TF-IDF Model"]:::ml
        Similarity["Similarity Logic"]:::ml
        Recommender["Recommender Orchestration"]:::ml
        MLUtils["ML Utilities"]:::ml
        ModelArtifact["model.pkl"]:::data
        SimilarityArtifact["similarity_matrix.pkl"]:::data
    end

    %% Scraping Subsystem
    subgraph "Scraping Subsystem"
        OpenLibScraper["OpenLibrary Scraper"]:::ml
        BooksScraper["BooksToScrape Scraper"]:::ml
        ScrapingService["Scraping Service"]:::business
    end

    %% Utilities & External
    subgraph "Utilities & External Services"
        Config["Config Loader"]:::util
        EmailService["Email Service (SMTP)"]:::util
        Security["Security Helpers"]:::util
        Helpers["General Helpers"]:::util
        SMTP["SMTP Server"]:::external
        OpenLibraryAPI["OpenLibrary API"]:::external
        BooksToScrapeAPI["BooksToScrape API"]:::external
    end

    %% Data Files Storage
    subgraph "Data Storage & Artifacts"
        RawCSV["Raw CSVs"]:::data
        CleanCSV["Cleaned CSVs"]:::data
        RecoArtifacts["Recommendation Artifacts"]:::data
    end

    %% Dependencies & Flows
    Browser -->|HTTP/HTML or JSON| FastAPIApp
    Scheduler -->|CLI Trigger| ScrapingService

    FastAPIApp -->|routes to| Routers
    Routers -->|calls| Services
    Services -->|queries| ORM
    ORM -->|SQL Queries| Database
    Services -->|renders| Templates
    Services -->|serves| Static

    Services -->|uses| TFIDF
    Services -->|uses| Similarity
    Services -->|uses| Recommender
    Services -->|calls| MLUtils
    TFIDF -->|reads/writes| ModelArtifact
    Similarity -->|reads/writes| SimilarityArtifact

    ScrapingService -->|invokes| OpenLibScraper
    ScrapingService -->|invokes| BooksScraper
    OpenLibScraper -->|fetches| OpenLibraryAPI
    BooksScraper -->|fetches| BooksToScrapeAPI
    OpenLibScraper -->|writes| RawCSV
    BooksScraper -->|writes| RawCSV
    ScrapingService -->|cleans| CleanCSV
    ScrapingService -->|persists| Database
    ScrapingService -->|stores| RecoArtifacts

    Services -->|sends SMTP| EmailService
    EmailService -->|SMTP| SMTP

    Services -->|loads| Config
    Services -->|uses| Security
    Services -->|uses| Helpers

    %% Click Events
    click FastAPIApp "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/main.py"
    click Routers "https://github.com/younes-el-kadmiri/booksmart/tree/main/app/routers/"
    click Services "https://github.com/younes-el-kadmiri/booksmart/tree/main/app/services/"
    click ORM "https://github.com/younes-el-kadmiri/booksmart/tree/main/app/models/"
    click Database "https://github.com/younes-el-kadmiri/booksmart/blob/main/library.db"
    click TFIDF "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/ml/tfidf_model.py"
    click Similarity "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/ml/similarity.py"
    click Recommender "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/ml/recommender.py"
    click MLUtils "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/ml/utils.py"
    click ModelArtifact "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/ml/model.pkl"
    click SimilarityArtifact "https://github.com/younes-el-kadmiri/booksmart/blob/main/data/recommandations/similarity_matrix.pkl"
    click OpenLibScraper "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/scraping/openlibrary_scraper.py"
    click BooksScraper "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/scraping/scrap_books_toscrape.py"
    click Config "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/utils/config.py"
    click EmailService "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/utils/email_service.py"
    click Security "https://github.com/younes-el-kadmiri/booksmart/blob/main/app/utils/security.py"

    %% Styles / Legend
    classDef presentation fill:#CFE2F3,stroke:#6C8EBF,color:#0B5394;
    classDef business fill:#D9EAD3,stroke:#6AA84F,color:#274E13;
    classDef data fill:#FCE5CD,stroke:#E69138,color:#B45F06;
    classDef ml fill:#EAD1DC,stroke:#A64D79,color:#741B47;
    classDef util fill:#FFF2CC,stroke:#BF9000,color:#7F6000;
    classDef external fill:#D9D9D9,stroke:#7F7F7F,color:#3F3F3F;
```
