# biblioverse/biblioteca architecture

> Architecture diagram of the GitHub repository biblioverse/biblioteca, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/biblioverse/biblioteca
- Repository: https://github.com/biblioverse/biblioteca

## Overview

##### Main System Components

a) Frontend Layer:
- Vue.js components (assets/ReadEbook.vue)
- Webpack-managed assets
- Twig templates for server-side rendering
- Bootstrap-based UI components

b) Application Layer:
- Symfony Framework core
- Controllers (organized by domain: Book, User, OPDS, Kobo)
- Security components
- Service layer
- Twig Components for dynamic UI elements

c) Integration Layer:
- OPDS feed system
- Kobo device integration
- AI features integration (ChatGPT/Ollama)

d) Data Layer:
- Doctrine ORM
- Database migrations
- File system storage for ebooks
- Typesense search integration

##### Key Relationships to Highlight

- User authentication flow
- Book management operations
- Kobo sync operations
- OPDS feed generation
- AI suggestion processing
- File system interactions

##### Specific Implementation Details

a) Security Layer:
- Multiple authentication methods (standard, Kobo, OPDS)
- Voter-based authorization system

b) Book Management:
- File system management
- Metadata extraction
- Cover image processing
- Search functionality

c) Device Integration:
- Kobo device synchronization
- OPDS catalog generation
- Reading state tracking

d) AI Features:
- Book tagging
- Summary generation
- Integration with multiple AI providers

##### Component Relationships

Key interactions:
**User Interface ↔ Controllers ↔ Services ↔ Repositories ↔ Storage**
- ↕
- External Services
- (AI, Kobo)

##### Infrastructure Elements

Highlight:
- Docker container structure
- Development environment (DDEV)
- Backup system
- Command-line tools

Remember to emphasize the modular nature of the system, particularly how the core library management functions interact with the various integration points (Kobo, OPDS, AI). This will help developers understand both the current architecture and potential extension points.

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Frontend
        UI["User Interface"]:::frontend
        VueComp["Vue.js Components"]:::frontend
        TwigTemp["Twig Templates"]:::frontend
        Assets["Asset Management"]:::frontend
    end

    subgraph AppLayer["Application Layer"]
        Controllers["Controllers"]:::app
        Security["Security Components"]:::app
        Services["Service Layer"]:::app
        Forms["Form Handling"]:::app
        TwigComp["Twig Components"]:::app
        Voters["Security Voters"]:::app
    end

    subgraph Integration["Integration Layer"]
        OPDS["OPDS Feed System"]:::integration
        Kobo["Kobo Integration"]:::integration
        AI["AI Features"]:::integration
        subgraph AIProviders["AI Providers"]
            ChatGPT["ChatGPT"]:::external
            Ollama["Ollama"]:::external
        end
    end

    subgraph DataLayer["Data Layer"]
        DB[(Database)]:::storage
        FileSystem["File System Storage"]:::storage
        Migrations["Database Migrations"]:::storage
        Entities["Entity Definitions"]:::storage
        Repos["Data Repositories"]:::storage
        Search["Typesense Search"]:::storage
    end

    subgraph Support["Supporting Systems"]
        Config["Configuration"]:::support
        Trans["Translation System"]:::support
        CLI["Command Line Tools"]:::support
        Cache["Cache Layer"]:::support
        Queue["Message Queue"]:::support
    end

    UI --> Controllers
    VueComp --> Controllers
    TwigTemp --> TwigComp
    Controllers --> Services
    Services --> Repos
    Services --> FileSystem
    Controllers --> Security
    Security --> Voters
    Forms --> Controllers
    
    Services --> AI
    AI --> AIProviders
    Services --> OPDS
    Services --> Kobo
    
    Repos --> DB
    Repos --> Search
    Services --> Queue
    Services --> Cache

    classDef frontend fill:#e1f5fe,stroke:#01579b
    classDef app fill:#e8f5e9,stroke:#1b5e20
    classDef integration fill:#fff3e0,stroke:#e65100
    classDef storage fill:#fce4ec,stroke:#880e4f
    classDef external fill:#f3e5f5,stroke:#4a148c
    classDef support fill:#f5f5f5,stroke:#212121

    click VueComp "https://github.com/biblioverse/biblioteca/blob/main/assets/ReadEbook.vue"
    click TwigTemp "https://github.com/biblioverse/biblioteca/tree/main/templates"
    click Assets "https://github.com/biblioverse/biblioteca/tree/main/assets"
    click Controllers "https://github.com/biblioverse/biblioteca/tree/main/src/Controller"
    click Security "https://github.com/biblioverse/biblioteca/tree/main/src/Security"
    click Services "https://github.com/biblioverse/biblioteca/tree/main/src/Service"
    click Forms "https://github.com/biblioverse/biblioteca/tree/main/src/Form"
    click OPDS "https://github.com/biblioverse/biblioteca/tree/main/src/Controller/OPDS"
    click Kobo "https://github.com/biblioverse/biblioteca/tree/main/src/Controller/Kobo"
    click AI "https://github.com/biblioverse/biblioteca/tree/main/src/Ai"
    click Migrations "https://github.com/biblioverse/biblioteca/tree/main/migrations"
    click Entities "https://github.com/biblioverse/biblioteca/tree/main/src/Entity"
    click Repos "https://github.com/biblioverse/biblioteca/tree/main/src/Repository"
    click FileSystem "https://github.com/biblioverse/biblioteca/blob/main/src/Service/BookFileSystemManager.php"
    click Config "https://github.com/biblioverse/biblioteca/tree/main/config"
    click Trans "https://github.com/biblioverse/biblioteca/tree/main/translations"
    click CLI "https://github.com/biblioverse/biblioteca/tree/main/src/Command"
    click TwigComp "https://github.com/biblioverse/biblioteca/tree/main/src/Twig/Components"
    click Voters "https://github.com/biblioverse/biblioteca/tree/main/src/Security/Voter"
```
