# aravindr31/watchtower architecture

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

- Interactive diagram: https://gitdiagram.com/aravindr31/watchtower
- Repository: https://github.com/aravindr31/watchtower

## Overview

##### Project Type & Purpose
- This is a full-stack web application built on Astro.
- Purpose: serve static and dynamic pages that surface movie, TV, and music data.
- It combines:
- A client‐side UI (Astro pages & components)
- Serverless API endpoints (in src/pages/api/v1)
- A small local database and external third-party services (TMDB, Spotify, torrent metadata, etc.)

##### File Structure
- Top-level artifacts:
- astro.config.mjs, tailwind.config.mjs, tsconfig.json – Astro & build configurations
- public/ – static assets (favicon, images)
- src/
– layouts/ & pages/ – Astro templates and routes
– components/ – reusable UI pieces (Nav, Searchbar, ContentCard, etc.)
– lib/ – server-side helpers (db.js, authdata.js, tmdb wrappers)
– middleware.ts – global request middleware (auth checks)
- src/pages/api/v1/** – versioned serverless functions for auth, media lookup, user data
- Patterns:
- Atomic UI components + Layout → SSR pages.
- Serverless API layer mapped to /api/v1.
- lib/* modules used by API routes to talk to DB & external services.

##### Extract Key Insights from README
- It began as Astro’s “basics” starter, then extended with multiple API routes.

##### Main Components & Interactions
a. Client Browser
- Requests pages (HTML/CSS/JS) and interacts with UI.
b. Astro Server (SSR + Static Assets)
- Serves static files from public/.
- Renders pages/layouts/components on request.
c. Serverless API Layer (/api/v1)
- Auth endpoints: spotifyauth, verifytoken, markaswatched
- Media endpoints: movie, tv, music, tmdb wrappers
d. Local Database
- Handled via src/lib/db.js (e.g., user watch lists, tokens)
e. External Services
- TMDB API for movie/TV details
- Spotify API for music data & user profile
- Torrent metadata API for media availability
f. Middleware (src/middleware.ts)
- Global intercept for token validation, redirects, error handling

Interactions:
- Browser → Astro Server (page navigation)
- Browser JS → /api/v1 endpoints (fetch JSON)
- API endpoints → lib modules → DB & External APIs
- Responses flow back up to Browser

##### Architectural Patterns & Design Principles
- Separation of concerns: UI vs API vs data
- Versioned API (/api/v1) for future extensibility
- Modular “lib” layer for code reuse
- SSR for SEO + performance, with client fetches for dynamic data

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Client Layer"
        UI["Browser UI"]:::ui
        comp["UI Components"]:::ui
        pages["Astro Pages & Routes"]:::ui
        static["Static Assets (public/)"]:::ui
    end

    subgraph "Astro Server (SSR & Static)"
        server["Astro Server"]:::ui
        layout["Layout Templates"]:::ui
        pages2["SSR Pages"]:::ui
    end

    middleware["Global Middleware"]:::middleware

    subgraph "API Layer (/api/v1)"
        authgroup["Auth Endpoints"]:::api
        mediagroup["Media Endpoints"]:::api
        moviegroup["Movie Endpoints"]:::api
        tvgroup["TV Endpoints"]:::api
        musicgroup["Music Endpoints"]:::api
        tmdbgroup["TMDB Wrapper Endpoints"]:::api
    end

    subgraph "Library Helpers"
        dbhelper["Local DB Helper"]:::lib
        authhelper["Auth Data Helper"]:::lib
        movieslib["Movies Wrapper"]:::lib
        musiclib["Music Wrapper"]:::lib
        showslib["Shows Wrapper"]:::lib
        commonlib["Shared Exports"]:::lib
    end

    db["Local Database"]:::dbclass

    subgraph "External Services"
        tmdb["TMDB API"]:::ext
        spotify["Spotify API"]:::ext
        torrent["Torrent Metadata API"]:::ext
    end

    UI -->|"Page Requests"|server
    server --> layout
    server --> pages2
    pages2 --> UI

    UI --> middleware
    middleware --> server
    middleware --> authgroup
    middleware --> mediagroup
    middleware --> moviegroup
    middleware --> tvgroup
    middleware --> musicgroup
    middleware --> tmdbgroup

    authgroup --> authhelper
    mediagroup --> commonlib
    mediagroup --> torrent
    moviegroup --> movieslib
    tvgroup --> showslib
    musicgroup --> musiclib
    tmdbgroup --> commonlib

    dbhelper --> db
    authhelper --> db
    movieslib --> tmdb
    showslib --> tmdb
    musiclib --> spotify

    classDef ui fill:#D0E8FF,stroke:#0066CC,color:#000
    classDef api fill:#D0FFD6,stroke:#009933,color:#000
    classDef dbclass fill:#FFE8A8,stroke:#CC9900,color:#000
    classDef ext fill:#F0D0FF,stroke:#9900CC,color:#000
    classDef middleware fill:#F0F0F0,stroke:#666666,color:#000
    classDef lib fill:#E8E8E8,stroke:#888888,color:#000

    click comp "https://github.com/aravindr31/watchtower/tree/master/src/components/"
    click layout "https://github.com/aravindr31/watchtower/blob/master/src/layouts/Layout.astro"
    click pages "https://github.com/aravindr31/watchtower/tree/master/src/pages/"
    click static "https://github.com/aravindr31/watchtower/tree/master/public/"
    click authgroup "https://github.com/aravindr31/watchtower/tree/master/src/pages/api/v1/auth/"
    click mediagroup "https://github.com/aravindr31/watchtower/tree/master/src/pages/api/v1/media/"
    click moviegroup "https://github.com/aravindr31/watchtower/tree/master/src/pages/api/v1/movie/"
    click tvgroup "https://github.com/aravindr31/watchtower/tree/master/src/pages/api/v1/tv/"
    click musicgroup "https://github.com/aravindr31/watchtower/tree/master/src/pages/api/v1/music/"
    click tmdbgroup "https://github.com/aravindr31/watchtower/tree/master/src/pages/api/v1/tmdb/"
    click dbhelper "https://github.com/aravindr31/watchtower/blob/master/src/lib/db.js"
    click authhelper "https://github.com/aravindr31/watchtower/blob/master/src/lib/authdata.js"
    click movieslib "https://github.com/aravindr31/watchtower/blob/master/src/lib/movies.js"
    click musiclib "https://github.com/aravindr31/watchtower/blob/master/src/lib/music.js"
    click showslib "https://github.com/aravindr31/watchtower/blob/master/src/lib/shows.js"
    click commonlib "https://github.com/aravindr31/watchtower/blob/master/src/lib/commonExports.js"
    click middleware "https://github.com/aravindr31/watchtower/blob/master/src/middleware.ts"
```
