# tenvid/personallibrary architecture

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

- Interactive diagram: https://gitdiagram.com/tenvid/personallibrary
- Repository: https://github.com/tenvid/personallibrary

## Overview

##### Tipo de proyecto y propósito (qué debe reflejar el diagrama)
Este repositorio es una **aplicación web monolítica Django** para gestionar una biblioteca personal (**Libros, Autores, Editoriales**) con:
- **UI server-rendered** (templates HTML + Bootstrap).
- **API REST** para CRUD de las mismas entidades.
- **Admin de Django** estilizado con **Jazzmin**.
- **Persistencia SQLite** (db.sqlite3) y ficheros subidos (portadas) en **media/**.
- **Estáticos** (CSS) en **static/**.

Por tanto, el “mejor” diagrama no es de microservicios: es un **diagrama de contenedores/componentes** de un monolito Django, con énfasis en:
- Entradas (browser / REST clients)
- Routing (URLs)
- Vistas HTML vs endpoints API
- Capa de modelos/ORM
- Storage (SQLite + filesystem media/static)
- Admin
- (Opcional) ASGI/WSGI server para despliegue

##### Lectura de la estructura (pistas arquitectónicas en el árbol)
Puntos clave del file tree:

**Raíz**
- `pyproject.toml`, `uv.lock`: dependencias y entorno (uv).
- `doc/img/*`: assets para documentación.

**Proyecto Django**
- `personal_library/manage.py`: entrypoint de Django.
- `personal_library/personal_library/`: paquete del proyecto (settings/urls/asgi/wsgi).
- `settings.py`: configuración global (INSTALLED_APPS, MIDDLEWARE, DB, STATIC/MEDIA).
- `urls.py`: routing global (incluye `core.urls`, admin, y endpoints API).
- `asgi.py` / `wsgi.py`: modos de ejecución/despliegue.

**App principal**
- `personal_library/core/`: app con dominio y lógica.
- `models.py`: entidades (Book/Author/Publisher y relaciones).
- `migrations/0001_initial.py`: esquema inicial.
- `admin.py`: registro de modelos (Jazzmin afecta a UI, pero el admin sigue siendo Django admin).
- `urls.py`: rutas de la app.
- `views.py` y `_views/*.py`: vistas HTML (probable separación por entidad).
- `templates/core/*.html`: UI server-rendered.
- `api/*.py`: endpoints REST (books/authors/publishers).
- `tests.py`: pruebas (mínimas en este repo).
- `db.sqlite3`: base de datos local.
- `media/book_covers`: storage de archivos subidos.
- `static/css/style.css`: estáticos.

Esto sugiere una arquitectura **por capas dentro de una sola app**: URLs → Views/API → ORM Models → DB / Storage, más Templates/Static para la presentación.

##### Qué buscar en README para orientar el diagrama
La README confirma explícitamente:
- CRUD completo de libros/autores/editoriales
- Búsqueda de libros
- API REST con endpoints `/api/...`
- Admin con Jazzmin
- SQLite pre-cargada
- Bootstrap 5

Así que el diagrama debe mostrar **dos superficies de consumo** (UI y API) y su convergencia en los **mismos modelos**.

##### Componentes principales a incluir (nivel contenedor)
Dibuja estos bloques (como mínimo):

##### Cliente Web (Browser)
- Consume páginas HTML.
- Descarga CSS/estáticos.
- Puede subir portadas (media).

##### Clientes API (REST)
- Postman/CLI/otro frontend (aunque aquí no hay SPA).
- Consume JSON endpoints `/api/...`.

##### Django App (Monolito)
Subdivide internamente (esto hace el diagrama “muy detallado” sin inventar microservicios):
- **URL Router**
- `personal_library/urls.py` (global)
- `core/urls.py` (app)
- **HTML Views**
- `core/views.py` + `core/_views/{books,authors,publishers}.py`
- **REST API Views**
- `core/api/{books,authors,publishers}.py`
- **Templates**
- `core/templates/core/*.html`
- **Static files**
- `static/css/style.css` (y Bootstrap 5 como dependencia frontend)
- **Django Admin**
- `core/admin.py` (+ Jazzmin como “theme/plugin”)
- **Domain/ORM Models**
- `core/models.py`
- **Migrations**
- `core/migrations/*` (útil para reflejar ownership del esquema)

##### Persistencia / Storage
- **SQLite DB**
- `db.sqlite3`
- **Media filesystem**
- `media/book_covers/*`
- (Opcional) **Static filesystem**
- `static/*` (en dev Django sirve; en prod lo serviría un web server/CDN)

##### Relaciones e interacciones (flechas de datos)
Dibuja flechas con direcciones claras:

- Browser → Django URL Router → HTML Views → Templates → HTML Response → Browser
- Browser → (GET) Static files (CSS) → Browser
- Browser → (upload) Media (book covers) → Django View/API → filesystem `media/`

- REST Client → Django URL Router → API endpoints → ORM Models → SQLite
- HTML Views → ORM Models → SQLite
- Admin UI (Browser) → `/admin/` → Django Admin → ORM Models → SQLite

Incluye también:
- ORM Models ↔ SQLite (lectura/escritura)
- Templates depend on context from Views (render server-side)

##### Patrones/decisiones arquitectónicas a resaltar
- **Monolito Django con una app principal (`core`)**
- **Separación de interfaz**:
- Server-side rendered MVC-ish: URL → View → Template
- API REST paralela: URL → API View → JSON
- **Mismo modelo para UI y API** (single source of truth del dominio)
- **Storage dual**: DB relacional + filesystem (media)
- **Admin como canal alterno de CRUD** (Django Admin + Jazzmin)

##### Tecnologías relevantes a etiquetar en el diagrama
- **Django** (router, views, templates, ORM, admin)
- **SQLite**
- **Bootstrap 5** (frontend styling)
- **Jazzmin** (admin theme)
- **ASGI/WSGI** (entrypoints de serving: `asgi.py`, `wsgi.py`)
- **uv** (tooling/packaging; opcional en diagrama de runtime, útil en “build/dev workflow”)

##### Cómo adaptar el diagrama al tipo de proyecto (full-stack Django monolito)
Para este caso, dibuja **dos diagramas complementarios** (recomendación para máxima precisión):

- Browser(s) / API client(s)
- Django application (single container)
- SQLite database file
- Media filesystem
- Static assets (served by Django in dev; opcional anotar “en prod: Nginx/CDN”)

Esto responde: “¿qué sistemas se comunican en runtime?”

Dentro del contenedor “Django app”, desglosa:
- `personal_library/` (settings, root urls, asgi/wsgi)
- `core/` (urls, views, api, models, templates, admin, migrations)
- data stores (db.sqlite3, media/, static/)
Y flechas:
- `root urls.py` → `core.urls`
- `core.urls` → (HTML views + API views)
- views/api → models → db
- html views → templates

Esto responde: “¿cómo está modularizado el monolito?”

##### Elementos visuales obligatorios (para que sea legible a nivel principal)
- **Etiquetas claras**: usa nombres del repo (ej. `core/api/books.py`) en subtítulos pequeños debajo del bloque “API”.
- **Flechas direccionales**:
- Sólidas para runtime calls (HTTP)
- Punteadas para dependencias internas (imports/render)
- **Colores / formas** (consistentes):
- Azul: clientes (Browser, REST client)
- Verde: Django runtime (router/views/admin)
- Naranja: storage (SQLite, media)
- Gris: assets (templates/static)
- **Agrupación por boundaries**:
- Un rectángulo grande “Django Project: personal_library”
- Dentro, sub-rectángulo “App: core”

#### 7) “Muy detallado” sin sobrepensar: lista de componentes a descomponer al máximo (concretos de este repo)
Si quieres el diagrama más “fiel” posible a este proyecto, separa explícitamente:
- **UI Pages** (como nodos lógicos): Books list/detail/edit, Authors list/detail/edit, Publishers list/detail/edit (`templates/core/*`)
- **API Resources**: Books, Authors, Publishers (`core/api/*`)
- **Views por entidad**: `core/_views/books.py`, `authors.py`, `publishers.py`
- **Rutas**:
- Root: `personal_library/urls.py`
- App: `core/urls.py`
- **Modelo de datos**: `core/models.py` (y anota relaciones principales: Book ↔ Author/Publisher si aplica)
- **Admin**: `core/admin.py` (con Jazzmin)
- **Storage**:
- `db.sqlite3`
- `media/book_covers`
- `static/css/style.css`

Con esto, el diagrama no inventa piezas externas y aun así captura “todas las partes” relevantes.

##### Flechas: clientes → router; views/admin → ORM → SQLite; uploads → media

Eso produce un diagrama exacto y alineado con el repositorio.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% External Clients
  %% =========================
  subgraph "Clients"
    BROWSER["Web Browser\n(HTML pages + CSS + uploads)"]:::client
    REST["REST Client\n(Postman/CLI)"]:::client
  end

  %% =========================
  %% Runtime / Deployment Surface
  %% =========================
  subgraph "Runtime / Deployment"
    ASGI["ASGI Server\n(asgi.py)"]:::runtime
    WSGI["WSGI Server\n(wsgi.py)"]:::runtime
  end

  %% =========================
  %% Django Monolith
  %% =========================
  subgraph "Django Monolith: personal_library"
    MANAGE["Django Entrypoint\n(manage.py)"]:::tooling

    subgraph "Project Package: personal_library/"
      SETTINGS["Global Settings\n(settings.py)"]:::django
      ROOTURLS["Root URL Router\n(urls.py)"]:::router
    end

    subgraph "App: core/"
      COREURLS["App URL Router\n(core/urls.py)"]:::router

      subgraph "UI (Server-rendered HTML)"
        VIEWS["HTML Views\n(core/views.py)"]:::django

        subgraph "Views by Entity\n(core/_views/...)"
          VBOOKS["Books Views\n(core/_views/books.py)"]:::django
          VAUTH["Authors Views\n(core/_views/authors.py)"]:::django
          VPUB["Publishers Views\n(core/_views/publishers.py)"]:::django
        end

        subgraph "Templates\n(core/templates/core/...)"
          TBASE["base.html"]:::asset
          TINDEX["index.html"]:::asset

          subgraph "Book Pages"
            TBOOKD["book_detail.html"]:::asset
            TBOOKE["book_edit.html"]:::asset
          end

          subgraph "Author Pages"
            TAUTHL["authors.html"]:::asset
            TAUTHD["author_detail.html"]:::asset
            TAUTHE["author_edit.html"]:::asset
          end

          subgraph "Publisher Pages"
            TPUBL["publishers.html"]:::asset
            TPUBD["publisher_detail.html"]:::asset
            TPUBE["publisher_edit.html"]:::asset
          end
        end
      end

      subgraph "REST API\n(/api/...)"
        APIPKG["API Package\n(core/api/)"]:::api
        APIBOOKS["Books Resource\n(core/api/books.py)"]:::api
        APIAUTH["Authors Resource\n(core/api/authors.py)"]:::api
        APIPUB["Publishers Resource\n(core/api/publishers.py)"]:::api
      end

      subgraph "Admin\n(/admin/)"
        ADMIN["Django Admin\n(core/admin.py)\n(Jazzmin theme)"]:::admin
      end

      subgraph "Domain / Data Access"
        MODELS["ORM Models\n(core/models.py)\nBook / Author / Publisher"]:::data
        MIGR["Migrations\n(0001_initial.py)"]:::data
      end

      TESTS["Tests\n(core/tests.py)"]:::tooling
    end

    subgraph "Tooling / Dependencies"
      PYPROJ["pyproject.toml"]:::tooling
      UVLOCK["uv.lock"]:::tooling
    end
  end

  %% =========================
  %% Storage
  %% =========================
  subgraph "Storage"
    DB[("SQLite DB\n(db.sqlite3)")]:::storage
    MEDIA[("Media Filesystem\n(media/book_covers/)")]:::storage
    STATIC["Static Assets\n(static/css/style.css)\n(+ Bootstrap 5)"]:::asset
  end

  %% =========================
  %% Runtime Flows (solid)
  %% =========================
  BROWSER -->|"HTTP(S) requests"| ASGI
  BROWSER -->|"HTTP(S) requests"| WSGI
  REST -->|"HTTP(S) /api/*"| ASGI
  REST -->|"HTTP(S) /api/*"| WSGI

  ASGI -->|"routes"| ROOTURLS
  WSGI -->|"routes"| ROOTURLS

  BROWSER -->|"GET /static/*"| STATIC
  BROWSER -->|"upload covers"| MEDIA

  %% =========================
  %% Internal Wiring (dotted)
  %% =========================
  ROOTURLS -.->|"include core.urls"| COREURLS

  COREURLS -.->|"dispatch HTML routes"| VIEWS
  COREURLS -.->|"dispatch API routes"| APIPKG
  COREURLS -.->|"dispatch admin routes"| ADMIN

  VIEWS -.->|"delegates"| VBOOKS
  VIEWS -.->|"delegates"| VAUTH
  VIEWS -.->|"delegates"| VPUB

  VIEWS -.->|"render"| TBASE
  VIEWS -.->|"render"| TINDEX
  VBOOKS -.->|"render"| TBOOKD
  VBOOKS -.->|"render"| TBOOKE
  VAUTH -.->|"render"| TAUTHL
  VAUTH -.->|"render"| TAUTHD
  VAUTH -.->|"render"| TAUTHE
  VPUB -.->|"render"| TPUBL
  VPUB -.->|"render"| TPUBD
  VPUB -.->|"render"| TPUBE

  APIPKG -.->|"books"| APIBOOKS
  APIPKG -.->|"authors"| APIAUTH
  APIPKG -.->|"publishers"| APIPUB

  VBOOKS -.->|"ORM CRUD"| MODELS
  VAUTH -.->|"ORM CRUD"| MODELS
  VPUB -.->|"ORM CRUD"| MODELS
  APIBOOKS -.->|"ORM CRUD"| MODELS
  APIAUTH -.->|"ORM CRUD"| MODELS
  APIPUB -.->|"ORM CRUD"| MODELS
  ADMIN -.->|"ORM CRUD"| MODELS

  MODELS -->|"read/write"| DB
  MIGR -.->|"schema evolution"| DB
  VBOOKS -.->|"store/retrieve cover paths"| MEDIA
  APIBOOKS -.->|"store/retrieve cover paths"| MEDIA

  %% =========================
  %% Click Events (mapped paths)
  %% =========================
  click MANAGE "https://github.com/tenvid/personallibrary/blob/main/personal_library/manage.py"
  click SETTINGS "https://github.com/tenvid/personallibrary/blob/main/personal_library/personal_library/settings.py"
  click ROOTURLS "https://github.com/tenvid/personallibrary/blob/main/personal_library/personal_library/urls.py"
  click ASGI "https://github.com/tenvid/personallibrary/blob/main/personal_library/personal_library/asgi.py"
  click WSGI "https://github.com/tenvid/personallibrary/blob/main/personal_library/personal_library/wsgi.py"

  click COREURLS "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/urls.py"
  click VIEWS "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/views.py"
  click VBOOKS "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/_views/books.py"
  click VAUTH "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/_views/authors.py"
  click VPUB "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/_views/publishers.py"

  click APIPKG "https://github.com/tenvid/personallibrary/tree/main/personal_library/core/api/"
  click APIBOOKS "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/api/books.py"
  click APIAUTH "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/api/authors.py"
  click APIPUB "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/api/publishers.py"

  click TBASE "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/base.html"
  click TINDEX "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/index.html"
  click TBOOKD "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/book_detail.html"
  click TBOOKE "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/book_edit.html"
  click TAUTHL "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/authors.html"
  click TAUTHD "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/author_detail.html"
  click TAUTHE "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/author_edit.html"
  click TPUBL "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/publishers.html"
  click TPUBD "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/publisher_detail.html"
  click TPUBE "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/templates/core/publisher_edit.html"

  click ADMIN "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/admin.py"
  click MODELS "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/models.py"
  click MIGR "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/migrations/0001_initial.py"
  click DB "https://github.com/tenvid/personallibrary/blob/main/personal_library/db.sqlite3"
  click MEDIA "https://github.com/tenvid/personallibrary/tree/main/personal_library/media/book_covers/"
  click STATIC "https://github.com/tenvid/personallibrary/blob/main/personal_library/static/css/style.css"
  click TESTS "https://github.com/tenvid/personallibrary/blob/main/personal_library/core/tests.py"
  click PYPROJ "https://github.com/tenvid/personallibrary/blob/main/pyproject.toml"
  click UVLOCK "https://github.com/tenvid/personallibrary/blob/main/uv.lock"
  click COREURLS "https://github.com/tenvid/personallibrary/tree/main/personal_library/core/"
  click SETTINGS "https://github.com/tenvid/personallibrary/tree/main/personal_library/personal_library/"

  %% =========================
  %% Styles
  %% =========================
  classDef client fill:#d6ecff,stroke:#1f5fbf,stroke-width:1px,color:#0b2a4a
  classDef runtime fill:#c8f7dc,stroke:#167a3f,stroke-width:1px,color:#0f3a22
  classDef django fill:#d8f5d0,stroke:#2e7d32,stroke-width:1px,color:#16351a
  classDef router fill:#baf0c2,stroke:#1b5e20,stroke-width:1px,color:#0f2d12
  classDef api fill:#c7f3ff,stroke:#007c91,stroke-width:1px,color:#05333b
  classDef admin fill:#f6d6ff,stroke:#7b1fa2,stroke-width:1px,color:#3b0f4b
  classDef data fill:#ffe6b3,stroke:#b26a00,stroke-width:1px,color:#4a2a00
  classDef storage fill:#ffd1b8,stroke:#b54500,stroke-width:1px,color:#4a1d00
  classDef asset fill:#eeeeee,stroke:#616161,stroke-width:1px,color:#1f1f1f
  classDef tooling fill:#fff7cc,stroke:#9a8700,stroke-width:1px,color:#3a3300
```
