# livrariadev/livraria architecture

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

- Interactive diagram: https://gitdiagram.com/livrariadev/livraria
- Repository: https://github.com/livrariadev/livraria

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Docker Compose Boundary
    subgraph "Docker Compose" 
        direction TB
        VueApp["Vue App"]:::frontend
        FastAPI["FastAPI Server"]:::backend
        RasPiNFC["RasPi NFC Service"]:::edge
    end

    %% CI/CD Swimlane
    subgraph "CI/CD Pipelines"
        direction TB
        CI["GitHub CI"]:::external
        CD["GitHub CD"]:::external
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Firebase["Firebase Auth/DB"]:::external
        Gemini["Google Gemini AI"]:::external
        BookAPIs["CiNii/Calil/Rakuten APIs"]:::external
        MongoDB["MongoDB(Optional)"]:::external
    end

    %% Documentation
    Docs["Documentation"]:::external

    %% Interactions
    VueApp -->|"HTTPS/JSON"| FastAPI
    VueApp -->|"HTTP/JSON"| RasPiNFC
    VueApp -->|"Firebase SDK"| Firebase

    FastAPI -->|"Firebase Admin SDK"| Firebase
    FastAPI -->|"REST/JSON"| BookAPIs
    FastAPI -->|"HTTPS/JSON"| Gemini
    FastAPI -->|"JSON"| MongoDB

    RasPiNFC -->|"pyscard"| CardReader(("Card Reader HW")):::external
    RasPiNFC -->|"REST/JSON"| FastAPI

    CI -->|uses| DockerCompose[("docker-compose.yml")]:::external
    CD -->|deploys| DockerCompose

    VueApp -->|docs| Docs
    FastAPI -->|docs| Docs
    RasPiNFC -->|docs| Docs

    %% Click Events - Frontend
    click VueApp "https://github.com/livrariadev/livraria/tree/main/frontend/"
    click VueApp "https://github.com/livrariadev/livraria/tree/main/frontend/Dockerfile"
    click VueApp "https://github.com/livrariadev/livraria/blob/main/frontend/src/services/api.js"
    click VueApp "https://github.com/livrariadev/livraria/blob/main/frontend/src/services/nfc.js"
    click VueApp "https://github.com/livrariadev/livraria/blob/main/frontend/src/firebaseConfig.js"
    click VueApp "https://github.com/livrariadev/livraria/tree/main/frontend/src/components"

    %% Click Events - Backend
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/run.py"
    click FastAPI "https://github.com/livrariadev/livraria/tree/main/backend/Dockerfile"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/server.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/routers/search.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/models.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/datastore.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/llm.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/legacy/gemini.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/api/legacy/llm.py"
    click FastAPI "https://github.com/livrariadev/livraria/tree/main/backend/api/prompts/"

    %% Click Events - Book Search Adapters
    click BookAPIs "https://github.com/livrariadev/livraria/blob/main/backend/search/cinii_search.py"
    click BookAPIs "https://github.com/livrariadev/livraria/blob/main/backend/search/calil.py"
    click BookAPIs "https://github.com/livrariadev/livraria/blob/main/backend/search/google_books.py"
    click BookAPIs "https://github.com/livrariadev/livraria/blob/main/backend/search/rakuten_books.py"
    click BookAPIs "https://github.com/livrariadev/livraria/tree/main/backend/search/rakuten_books_genre/"

    %% Click Events - Face Recognition
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/face_rec/face_detection.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/face_rec/learn_face.py"
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/face_rec/face_encodings.json"

    %% Click Events - NFC Mock Server
    click FastAPI "https://github.com/livrariadev/livraria/blob/main/backend/tools/mock_nfc_server.py"

    %% Click Events - Tests
    click FastAPI "https://github.com/livrariadev/livraria/tree/main/backend/test/"

    %% Click Events - Raspberry Pi NFC
    click RasPiNFC "https://github.com/livrariadev/livraria/blob/main/raspi/nfc/nfc_api_server.py"
    click RasPiNFC "https://github.com/livrariadev/livraria/blob/main/raspi/nfc/nfc-api.service"
    click RasPiNFC "https://github.com/livrariadev/livraria/blob/main/raspi/nfc/setup.sh"
    click RasPiNFC "https://github.com/livrariadev/livraria/blob/main/raspi/nfc/demo.html"

    %% Click Events - Orchestration & CI/CD & Docs
    click DockerCompose "https://github.com/livrariadev/livraria/blob/main/docker-compose.yml"
    click CI "https://github.com/livrariadev/livraria/blob/main/ .github/workflows/ci.yaml"
    click CD "https://github.com/livrariadev/livraria/blob/main/ .github/workflows/cd.yaml.disabled"
    click Docs "https://github.com/livrariadev/livraria/tree/main/docs/"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#3B82F6,color:#1E3A8A
    classDef backend fill:#E6F4EA,stroke:#10B981,color:#065F46
    classDef edge fill:#FFE8D0,stroke:#F59E0B,color:#92400E
    classDef external fill:#F3F4F6,stroke:#6B7280,color:#374151
```
