How livrariadev/livraria works
Project Type and Purpose
• LiVraria is a full-stack, next-generation library recommendation system.
• Frontend: Vue 3 + Vite + TailwindCSS for UI and Firebase auth.
• Backend: FastAPI service providing REST/AI endpoints, integrating Firebase Admin SDK, Google Gemini API, optional MongoDB, NFC interactions.
• Edge component: Raspberry Pi runs an NFC API server for card-based login.
• External services: Firebase Auth/DB, CiNii/Calil/Rakuten book APIs, Google Gemini AI.
File Structure Highlights
• Top-level: frontend/, backend/, raspi/, docs/, .github/, docker-compose.yml
• backend/
• run.py & Dockerfile – entrypoint and containerization
• api/ – FastAPI server, routers, models, datastore layer (JSON/Mongo), LLM adapters, prompt files
• search/ – connectors to CiNii, Calil, Rakuten
• face_rec/ – local face detection/recognition utilities
• test/ – integration and unit tests
• frontend/
• src/components – Vue components (Login, BookSearch, MemberInfo, SecondaryDisplay…)
• src/services – api.js (REST client to FastAPI), nfc.js (calls RasPi NFC API)
• firebaseConfig.js – Firebase initialization
• Dockerfile – container build
• raspi/nfc/
• nfc_api_server.py – Flask or FastAPI–like microservice exposing NFC reader endpoints
• systemd service file, setup scripts
• docker-compose.yml orchestrates frontend, backend, and optionally raspi container(s).
Key Architecture Patterns
• Separation of concerns:
• Presentation layer (Vue) ↔ API layer (FastAPI) ↔ Data/AI layers ↔ External services
• Modular backend: routers → controllers → datastore → AI adapters
• Microservice for NFC on Raspberry Pi
• Asynchronous or synchronous HTTP calls between components
• Containerization with Docker Compose for local/dev orchestration
Main Components & Interactions
a. Frontend (Browser/Vue app)
• Hosts UI, handles user interactions (login, search, recommendations)
• Calls FastAPI endpoints over HTTP(S)
• Calls RasPi NFC microservice via example endpoint (e.g., POST /nfc/auth)
• Uses Firebase JS SDK for email/password authentication
b. Backend (FastAPI service)
• HTTP API layer: routers/search, routers/auth, routers/ai
• Datastore: reads/writes JSON or MongoDB (configurable)
• LLM integration:
• Google Gemini via API key
• Ollama fallback if configured
• Book search adapters: CiNii, Calil, Rakuten
• Face recognition module (optional to unlock additional features)
c. Raspberry Pi NFC Microservice
• Runs on Pi, reads card IDs, exposes REST endpoints
• Systemd service for auto-start
d. External Services
• Firebase Authentication & Firestore/Realtime Database
• Google Gemini AI API
• CiNii, Calil, Rakuten book data APIs
• Optional: MongoDB instance (local or Atlas)
Architectural Patterns & Principles
• “API Gateway” style: FastAPI acts as a unified entrypoint for all business logic.
• Adapter pattern for search providers and LLM backends.
• Microservice boundary for NFC on the Pi to isolate hardware integration.
• Use environment-based configuration (dotenv) and containerization for portability.