# breaksmodded/mi_catalogo architecture

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

- Interactive diagram: https://gitdiagram.com/breaksmodded/mi_catalogo
- Repository: https://github.com/breaksmodded/mi_catalogo

## Overview

##### Project Type and Purpose
- This is a full-stack, single-page application for personal movie/series cataloging.
- Frontend: React + Vite, deployed on Vercel.
- Backend: FastAPI + SQLite, deployed on Render.
- Purpose: Let users browse, search, filter, annotate, rate, and get stats on their watched content, enriched via TMDb.

##### File Structure Analysis
- Top level:
- package.json & public/: React/Vite frontend
- db.sqlite3: local development database (backend)
- src/: React application code
- src/components/: UI pieces (Navbar, SectionRow, DetailModal, Filters, Resumen, etc.)
- src/context/: React contexts for language & notifications
- src/hooks/: custom hooks for translations, dynamic posters, caching
- src/i18n/: internationalization setup & language files
- src/utils/: helper functions (e.g., contentTranslation)
- README references an unshown backend/ directory with FastAPI entry point (main.py, routers, models)

##### README Insights
- Backend exposes REST endpoints for CRUD on movies, series, lists, tags
- Automatic TMDb integration for metadata
- Frontend consumes backend via environment-configured API URL

##### Main Components
a. Frontend SPA (React + Vite)
- UI Components (Navbar, Carousels, Modals, Filters, Charts)
- Context Providers (LanguageContext, NotificationContext)
- Custom Hooks (useTranslations, useDynamicPoster, cacheFetch)
- i18n Module (languages/en.js, languages/es.js)
b. Backend API (FastAPI)
- HTTP Server (uvicorn + FastAPI)
- Routers/Endpoints (movies, series, lists, tags, stats)
- Database Layer (SQLite via SQLModel/SQLAlchemy)
- External Service Client (TMDb API)
c. Data Store
- SQLite database
d. External Services
- TMDb REST API (metadata provider)
e. Users & Deployment
- User Browser
- Vercel (frontend hosting)
- Render (backend hosting)

##### Relationships & Data Flows
- User Browser → (HTTP/HTTPS) → Frontend SPA
- Frontend → (REST calls) → FastAPI Backend
- Backend → (SQL queries) → SQLite DB
- Backend → (HTTP calls) → TMDb API
- Backend → processes & returns JSON → Frontend
- Frontend → renders UI, updates Context, invokes Custom Hooks

##### Architectural Patterns & Principles
- SPA with client-side routing (React Router)
- Component-based UI (separation into reusable pieces)
- Context API for cross-cutting concerns (i18n, notifications)
- Custom hooks for encapsulating logic (data fetching, caching, translation)
- RESTful API backend with clear resource routers
- Layered separation: Presentation (React), Business Logic (FastAPI), Persistence (SQLite)

##### Final Advice
- Start broad: outline user → frontend → backend → database/external API.
- Drill down backend: routers, service layer, DB connector, TMDb client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    UserBrowser(["User Browser"]):::external

    %% Frontend Deployment
    subgraph "Vercel - Frontend"
        direction TB
        FrontendSPA(["Frontend SPA (React + Vite)"]):::frontend
        IndexHTML(["index.html"]):::frontend
        subgraph "UI Components"
            direction TB
            NavbarComp(["Navbar Component"]):::frontend
            SectionRowComp(["SectionRow Component"]):::frontend
            DetailModalComp(["DetailModal Component"]):::frontend
            FiltersComp(["Filters Component"]):::frontend
            GeneroChartComp(["GeneroChart Component"]):::frontend
            ResumenComp(["Resumen Component"]):::frontend
        end
        subgraph "Context Providers"
            direction TB
            LanguageContext(["LanguageContext"]):::frontend
            NotificationContext(["NotificationContext"]):::frontend
        end
        subgraph "Custom Hooks"
            direction TB
            useTranslationsHook(["useTranslations Hook"]):::frontend
            useDynamicPosterHook(["useDynamicPoster Hook"]):::frontend
            useTranslatedContentHook(["useTranslatedContent Hook"]):::frontend
            cacheFetchHook(["cacheFetch Hook"]):::frontend
        end
        subgraph "i18n Module"
            direction TB
            i18nIndex(["i18n Entry Point"]):::frontend
            enLang(["English Language File"]):::frontend
            esLang(["Spanish Language File"]):::frontend
        end
        subgraph "Utils"
            direction TB
            contentTranslationUtil(["contentTranslation Utility"]):::frontend
        end
    end

    %% Backend Deployment
    subgraph "Render - Backend"
        direction TB
        FastAPI(["FastAPI Server"]):::backend
        Routers(["API Routers (movies, series, lists, tags, stats)"]):::backend
        DBLayer(["Database Layer (SQLModel)"]):::backend
        TMDbClient(["TMDb Client"]):::backend
        SQLiteDB(("SQLite Database")):::db
    end

    %% External Service
    TMDbAPI(["TMDb REST API"]):::external

    %% Data Flows
    UserBrowser -->|"Loads SPA (HTTPS)"| FrontendSPA
    FrontendSPA -->|"GET/POST Endpoints"| FastAPI
    FastAPI -->|"SQL Queries"| SQLiteDB
    FastAPI -->|"Fetch metadata"| TMDbAPI
    FastAPI -->|"JSON Responses"| FrontendSPA

    %% Click Events
    click FrontendSPA "https://github.com/breaksmodded/mi_catalogo/tree/main//src"
    click NavbarComp "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/Navbar.js"
    click SectionRowComp "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/SectionRow.js"
    click DetailModalComp "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/DetailModal.js"
    click FiltersComp "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/Filters.js"
    click GeneroChartComp "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/GeneroChart.js"
    click ResumenComp "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/Resumen.js"
    click LanguageContext "https://github.com/breaksmodded/mi_catalogo/blob/main//src/context/LanguageContext.js"
    click NotificationContext "https://github.com/breaksmodded/mi_catalogo/blob/main//src/context/NotificationContext.js"
    click useTranslationsHook "https://github.com/breaksmodded/mi_catalogo/blob/main//src/hooks/useTranslations.js"
    click useDynamicPosterHook "https://github.com/breaksmodded/mi_catalogo/blob/main//src/hooks/useDynamicPoster.js"
    click useTranslatedContentHook "https://github.com/breaksmodded/mi_catalogo/blob/main//src/hooks/useTranslatedContent.js"
    click cacheFetchHook "https://github.com/breaksmodded/mi_catalogo/blob/main//src/components/cacheFetch.js"
    click i18nIndex "https://github.com/breaksmodded/mi_catalogo/blob/main//src/i18n/index.js"
    click enLang "https://github.com/breaksmodded/mi_catalogo/blob/main//src/i18n/languages/en.js"
    click esLang "https://github.com/breaksmodded/mi_catalogo/blob/main//src/i18n/languages/es.js"
    click contentTranslationUtil "https://github.com/breaksmodded/mi_catalogo/blob/main//src/utils/contentTranslation.js"
    click IndexHTML "https://github.com/breaksmodded/mi_catalogo/blob/main//public/index.html"
    click SQLiteDB "https://github.com/breaksmodded/mi_catalogo/blob/main//db.sqlite3"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef db fill:#F0E68C,stroke:#000,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef network stroke-dasharray: 5 5,color:#000
```
