How younes-el-kadmiri/booksmart works
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