# estudiagit/mis-series architecture

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

- Interactive diagram: https://gitdiagram.com/estudiagit/mis-series
- Repository: https://github.com/estudiagit/mis-series

## Overview

1. **What this repo is**
   - A private React 19 + TypeScript app, built with Vite, for managing a personal TV series list.
   - It is not a generic public SPA: almost every meaningful operation goes through Netlify Functions behind an access gate.

2. **Client shell**
   - `src/main.tsx`, `src/App.tsx`, and `src/index.css` define the browser app bootstrap and overall layout.
   - The UI is composed from `SeriesHeader`, `SeriesList`, `SeriesCard`, `SeriesForm`, `SeriesOptionsMenu`, `Toast`, and `AccessGate`.

3. **Authentication / access boundary**
   - Access is controlled by `APP_ACCESS_KEY`.
   - `AccessGate` and `useAppAccess` manage the “locked vs unlocked” app state.
   - On the backend, `netlify/functions/session.mjs` plus `_lib/access.mjs` likely validate the key and establish an authenticated session for later API calls.

4. **Domain state in the browser**
   - `useSeriesCollection` is the main client-side domain hook: it aggregates list loading, updates, ordering, and coordination with search/import/export actions.
   - Supporting hooks split responsibilities: `useSeriesFilters`, `useSeriesFormState`, `useSeriesDragAndDrop`, and `useSeriesJsonTransfer`.
   - This makes the UI mostly a thin layer over a shared series collection workflow.

5. **Series data model and UI flow**
   - The core entity is a “series” record defined in `src/types.ts`.
   - The UI flow is: user unlocks app → list is loaded → user filters/searches/reorders/edits series → changes are persisted back to the server.
   - `SeriesForm` handles create/edit input, while list/card components render and manipulate the collection.

6. **Backend persistence layer**
   - `netlify/functions/series-state.mjs` is the private API for reading and writing the series list.
   - The README says the data is stored in **Netlify Blobs**, so persistence is server-side object storage rather than a database.
   - This function is the main boundary for collection state synchronization between browser and storage.

7. **Metadata enrichment / external APIs**
   - `netlify/functions/series-search.mjs` provides search capabilities, probably used by the form to find series titles.
   - `_lib/series-metadata.mjs` and `src/services/seriesMetadataService.ts` indicate a metadata pipeline that queries **TVMaze**.
   - If `GEMINI_API_KEY` is configured, the backend can also translate descriptions via **Gemini** before returning metadata to the client.

8. **Shared server-side function library**
   - `_lib/http.mjs`, `_lib/env.mjs`, `_lib/access.mjs`, `_lib/series-shared.mjs`, and `_lib/series-metadata.mjs` are common server utilities.
   - These libraries centralize request/response handling, environment loading, auth checks, and series-shaped data normalization across multiple functions.
   - That keeps `session`, `series-state`, and `series-search` consistent.

9. **Client service layer**
   - `src/services/apiClient.ts` is the transport abstraction between React hooks and Netlify Functions.
   - `accessService`, `seriesStateService`, and `seriesMetadataService` isolate endpoint details from components/hooks.
   - This creates a clear split: UI logic in hooks/components, HTTP/protocol details in services.

10. **Local import/export and seeded data**
    - `public/mis_series.json` suggests a downloadable or importable snapshot of the user’s list.
    - `useSeriesJsonTransfer` likely handles JSON import/export, which is separate from the live Blobs-backed persistence path.
    - That gives the app an offline-friendly transfer path without changing the canonical server store.

11. **Deployment and local runtime**
    - Netlify is part of the architecture, not just hosting: `netlify.toml` and `netlify/functions/` are required for the app to work.
    - `npm run dev` uses `netlify dev` so the frontend and private functions run together locally, typically on `localhost:8888`.
    - Production is the same architecture: static Vite build plus Netlify Functions and Netlify Blobs.

12. **Quality and verification**
    - Tests are done with **Vitest** and **Testing Library**.
    - The test files around hooks and form components indicate the project validates domain logic and UI behavior at the unit/component level, rather than relying only on end-to-end checks.

Main entry points: [`src/hooks/useSeriesCollection.ts`](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesCollection.ts) (Collection hook), [`src/App.tsx`](https://github.com/estudiagit/mis-series/blob/main/src/App.tsx) (App shell), [`netlify/functions/series-state.mjs`](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/series-state.mjs) (State fn), [`netlify/functions/series-search.mjs`](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/series-search.mjs) (Search fn)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client app"]
  node_main["Main<br/>bootstrap<br/>[main.tsx]"]
  node_app["App shell<br/>layout<br/>[App.tsx]"]
  node_access_gate["Access gate<br/>auth-ui<br/>[AccessGate.tsx]"]
  node_header["Header<br/>[SeriesHeader.tsx]"]
  node_list["Series list<br/>ui-list<br/>[SeriesList.tsx]"]
  node_card["Series card<br/>ui-item<br/>[SeriesCard.tsx]"]
  node_form["Series form<br/>ui-form<br/>[SeriesForm.tsx]"]
  node_menu["Options menu<br/>ui-menu"]
  node_toast["Toast<br/>feedback-ui<br/>[Toast.tsx]"]
  node_access_hook["Access state<br/>hook-auth<br/>[useAppAccess.ts]"]
  node_collection_hook["Collection hook<br/>hook-domain"]
  node_filters_hook["Filters<br/>hook-domain"]
  node_form_hook["Form state<br/>hook-domain"]
  node_drag_hook["Drag and drop<br/>hook-domain"]
  node_json_hook["JSON transfer<br/>hook-domain"]
  node_api_client["API client<br/>transport<br/>[apiClient.ts]"]
  node_access_service["Access service<br/>service-auth<br/>[accessService.ts]"]
  node_state_service["Series service<br/>service-data"]
  node_meta_service["Metadata service<br/>service-enrichment"]
end

subgraph group_server["Netlify backend"]
  node_session_fn["Session fn<br/>netlify-function<br/>[session.mjs]"]
  node_state_fn["State fn<br/>netlify-function<br/>[series-state.mjs]"]
  node_search_fn["Search fn<br/>netlify-function<br/>[series-search.mjs]"]
  node_http_lib["HTTP utils<br/>server-lib<br/>[http.mjs]"]
  node_env_lib["Env utils<br/>server-lib<br/>[env.mjs]"]
  node_access_lib["Access utils<br/>server-lib<br/>[access.mjs]"]
  node_shared_lib["Series shared<br/>server-lib<br/>[series-shared.mjs]"]
  node_metadata_lib["Metadata lib<br/>server-lib"]
end

subgraph group_shared["Shared domain"]
  node_series_types["Series types<br/>domain-model<br/>[types.ts]"]
  node_seed_json["Seed JSON<br/>transfer-asset<br/>[mis_series.json]"]
end

subgraph group_tooling["Tooling"]
  node_vite["Vite build<br/>build-tool<br/>[vite.config.ts]"]
  node_netlify["Netlify config<br/>deploy-config<br/>[netlify.toml]"]
  node_vitest["Vitest<br/>test-runner<br/>[vitest.config.ts]"]
end

node_main -->|"boots"| node_app
node_app -->|"wraps"| node_access_gate
node_app -->|"composes"| node_header
node_app -->|"composes"| node_list
node_app -->|"composes"| node_toast
node_access_gate -->|"uses"| node_access_hook
node_list -->|"renders"| node_card
node_card -->|"exposes"| node_menu
node_app -->|"opens"| node_form
node_collection_hook -->|"coordinates"| node_filters_hook
node_collection_hook -->|"coordinates"| node_form_hook
node_collection_hook -->|"coordinates"| node_drag_hook
node_collection_hook -->|"coordinates"| node_json_hook
node_collection_hook -->|"persists"| node_state_service
node_collection_hook -->|"enriches"| node_meta_service
node_collection_hook -->|"shapes"| node_series_types
node_access_hook -->|"calls"| node_access_service
node_access_service -->|"uses"| node_api_client
node_state_service -->|"uses"| node_api_client
node_meta_service -->|"uses"| node_api_client
node_api_client -->|"invokes"| node_session_fn
node_api_client -->|"invokes"| node_state_fn
node_api_client -->|"invokes"| node_search_fn
node_session_fn -->|"uses"| node_http_lib
node_session_fn -->|"uses"| node_env_lib
node_session_fn -->|"uses"| node_access_lib
node_state_fn -->|"uses"| node_http_lib
node_state_fn -->|"uses"| node_env_lib
node_state_fn -->|"uses"| node_access_lib
node_state_fn -->|"uses"| node_shared_lib
node_search_fn -->|"uses"| node_http_lib
node_search_fn -->|"uses"| node_env_lib
node_search_fn -->|"uses"| node_shared_lib
node_search_fn -->|"uses"| node_metadata_lib
node_form_hook -->|"uses"| node_series_types
node_json_hook -->|"imports"| node_seed_json
node_vite -->|"builds"| node_main
node_netlify -->|"wires"| node_session_fn
node_netlify -->|"wires"| node_state_fn
node_netlify -->|"wires"| node_search_fn
node_vitest -->|"covers"| node_collection_hook
node_vitest -->|"covers"| node_form
node_vitest -->|"covers"| node_app

click node_main "https://github.com/estudiagit/mis-series/blob/main/src/main.tsx"
click node_app "https://github.com/estudiagit/mis-series/blob/main/src/App.tsx"
click node_access_gate "https://github.com/estudiagit/mis-series/blob/main/src/components/AccessGate.tsx"
click node_header "https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesHeader.tsx"
click node_list "https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesList.tsx"
click node_card "https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesCard.tsx"
click node_form "https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesForm.tsx"
click node_menu "https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesOptionsMenu.tsx"
click node_toast "https://github.com/estudiagit/mis-series/blob/main/src/components/Toast.tsx"
click node_access_hook "https://github.com/estudiagit/mis-series/blob/main/src/hooks/useAppAccess.ts"
click node_collection_hook "https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesCollection.ts"
click node_filters_hook "https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesFilters.ts"
click node_form_hook "https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesFormState.ts"
click node_drag_hook "https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesDragAndDrop.ts"
click node_json_hook "https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesJsonTransfer.ts"
click node_api_client "https://github.com/estudiagit/mis-series/blob/main/src/services/apiClient.ts"
click node_access_service "https://github.com/estudiagit/mis-series/blob/main/src/services/accessService.ts"
click node_state_service "https://github.com/estudiagit/mis-series/blob/main/src/services/seriesStateService.ts"
click node_meta_service "https://github.com/estudiagit/mis-series/blob/main/src/services/seriesMetadataService.ts"
click node_series_types "https://github.com/estudiagit/mis-series/blob/main/src/types.ts"
click node_seed_json "https://github.com/estudiagit/mis-series/blob/main/public/mis_series.json"
click node_session_fn "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/session.mjs"
click node_state_fn "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/series-state.mjs"
click node_search_fn "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/series-search.mjs"
click node_http_lib "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/http.mjs"
click node_env_lib "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/env.mjs"
click node_access_lib "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/access.mjs"
click node_shared_lib "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/series-shared.mjs"
click node_metadata_lib "https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/series-metadata.mjs"
click node_vite "https://github.com/estudiagit/mis-series/blob/main/vite.config.ts"
click node_netlify "https://github.com/estudiagit/mis-series/blob/main/netlify.toml"
click node_vitest "https://github.com/estudiagit/mis-series/blob/main/vitest.config.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_app,node_access_gate,node_header,node_list,node_card,node_form,node_menu,node_toast,node_access_hook,node_collection_hook,node_filters_hook,node_form_hook,node_drag_hook,node_json_hook,node_api_client,node_access_service,node_state_service,node_meta_service toneBlue
class node_session_fn,node_state_fn,node_search_fn,node_http_lib,node_env_lib,node_access_lib,node_shared_lib,node_metadata_lib toneAmber
class node_series_types,node_seed_json toneMint
class node_vite,node_netlify,node_vitest toneRose
```

## Components

### Client app

React UI, hooks, and browser-side services.

- [Main](https://github.com/estudiagit/mis-series/blob/main/src/main.tsx): bootstrap · Vite entry that mounts the app. · `src/main.tsx`
- [App shell](https://github.com/estudiagit/mis-series/blob/main/src/App.tsx): layout · Top-level React composition and routing of the UI. · `src/App.tsx`
- [Access gate](https://github.com/estudiagit/mis-series/blob/main/src/components/AccessGate.tsx): auth-ui · Locked/unlocked app boundary in the browser. · `src/components/AccessGate.tsx`
- [Header](https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesHeader.tsx): ui-header · Top-level series page header and controls. · `src/components/SeriesHeader.tsx`
- [Series list](https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesList.tsx): ui-list · Collection viewport for rendering and interacting with series. · `src/components/SeriesList.tsx`
- [Series card](https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesCard.tsx): ui-item · Single series row/card representation and actions. · `src/components/SeriesCard.tsx`
- [Series form](https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesForm.tsx): ui-form · Create/edit form for series records. · `src/components/SeriesForm.tsx`
- [Options menu](https://github.com/estudiagit/mis-series/blob/main/src/components/SeriesOptionsMenu.tsx): ui-menu · Per-item actions and overflow controls. · `src/components/SeriesOptionsMenu.tsx`
- [Toast](https://github.com/estudiagit/mis-series/blob/main/src/components/Toast.tsx): feedback-ui · Transient client feedback notifications. · `src/components/Toast.tsx`
- [Access state](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useAppAccess.ts): hook-auth · Client access-state coordination and unlock flow. · `src/hooks/useAppAccess.ts`
- [Collection hook](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesCollection.ts): hook-domain · Main browser-side series workflow orchestration. · `src/hooks/useSeriesCollection.ts`
- [Filters](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesFilters.ts): hook-domain · Search and filter state for the series collection. · `src/hooks/useSeriesFilters.ts`
- [Form state](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesFormState.ts): hook-domain · Create/edit form state and validation coordination. · `src/hooks/useSeriesFormState.ts`
- [Drag and drop](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesDragAndDrop.ts): hook-domain · Ordering interactions for reordering series. · `src/hooks/useSeriesDragAndDrop.ts`
- [JSON transfer](https://github.com/estudiagit/mis-series/blob/main/src/hooks/useSeriesJsonTransfer.ts): hook-domain · Import/export of series snapshots via JSON. · `src/hooks/useSeriesJsonTransfer.ts`
- [API client](https://github.com/estudiagit/mis-series/blob/main/src/services/apiClient.ts): transport · Shared HTTP transport abstraction for function calls. · `src/services/apiClient.ts`
- [Access service](https://github.com/estudiagit/mis-series/blob/main/src/services/accessService.ts): service-auth · Client endpoint wrapper for session/access handling. · `src/services/accessService.ts`
- [Series service](https://github.com/estudiagit/mis-series/blob/main/src/services/seriesStateService.ts): service-data · Client endpoint wrapper for reading and writing series state. · `src/services/seriesStateService.ts`
- [Metadata service](https://github.com/estudiagit/mis-series/blob/main/src/services/seriesMetadataService.ts): service-enrichment · Client endpoint wrapper for series search and metadata lookups. · `src/services/seriesMetadataService.ts`

### Netlify backend

Functions and shared server-side helpers.

- [Session fn](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/session.mjs): netlify-function · Creates or validates an authenticated session. · `netlify/functions/session.mjs`
- [State fn](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/series-state.mjs): netlify-function · Private series list read/write API backed by Blobs. · `netlify/functions/series-state.mjs`
- [Search fn](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/series-search.mjs): netlify-function · Series search and metadata lookup API. · `netlify/functions/series-search.mjs`
- [HTTP utils](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/http.mjs): server-lib · Shared request/response helpers for functions. · `netlify/functions/_lib/http.mjs`
- [Env utils](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/env.mjs): server-lib · Environment loading and configuration helpers. · `netlify/functions/_lib/env.mjs`
- [Access utils](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/access.mjs): server-lib · Server-side access-key validation and auth helpers. · `netlify/functions/_lib/access.mjs`
- [Series shared](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/series-shared.mjs): server-lib · Series normalization and shared backend domain helpers. · `netlify/functions/_lib/series-shared.mjs`
- [Metadata lib](https://github.com/estudiagit/mis-series/blob/main/netlify/functions/_lib/series-metadata.mjs): server-lib · TVMaze/Gemini enrichment pipeline helpers. · `netlify/functions/_lib/series-metadata.mjs`

### Shared domain

Common types and transfer assets.

- [Series types](https://github.com/estudiagit/mis-series/blob/main/src/types.ts): domain-model · Shared series entity shape used across the app. · `src/types.ts`
- [Seed JSON](https://github.com/estudiagit/mis-series/blob/main/public/mis_series.json): transfer-asset · Importable/exportable sample series snapshot. · `public/mis_series.json`

### Tooling

Build, test, and deployment runtime.

- [Vite build](https://github.com/estudiagit/mis-series/blob/main/vite.config.ts): build-tool · Frontend bundling and dev server build toolchain. · `vite.config.ts`
- [Netlify config](https://github.com/estudiagit/mis-series/blob/main/netlify.toml): deploy-config · Local and production function/runtime wiring. · `netlify.toml`
- [Vitest](https://github.com/estudiagit/mis-series/blob/main/vitest.config.ts): test-runner · Unit and component test harness. · `vitest.config.ts`

## Connections

- Main → App shell: boots · Mounts the application shell.
- App shell → Access gate: wraps · Places the authenticated boundary around the UI.
- App shell → Header: composes · Renders the page header.
- App shell → Series list: composes · Renders the series collection viewport.
- App shell → Toast: composes · Displays user feedback notifications.
- Access gate → Access state: uses · Reads and updates unlocked app state.
- Series list → Series card: renders · Displays each series entry as a card.
- Series card → Options menu: exposes · Provides item-level actions.
- App shell → Series form: opens · Hosts create/edit workflows.
- Collection hook → Filters: coordinates · Combines search and filter state.
- Collection hook → Form state: coordinates · Coordinates form-driven collection edits.
- Collection hook → Drag and drop: coordinates · Coordinates reorder interactions.
- Collection hook → JSON transfer: coordinates · Coordinates import/export transfer flows.
- Collection hook → Series service: persists · Synchronizes the collection with server state.
- Collection hook → Metadata service: enriches · Fetches search and metadata data.
- Collection hook → Series types: shapes · Operates on the shared series entity model.
- Access state → Access service: calls · Delegates session creation and validation.
- Access service → API client: uses · Shares transport details.
- Series service → API client: uses · Shares transport details.
- Metadata service → API client: uses · Shares transport details.
- API client → Session fn: invokes · Calls the session function through the Netlify runtime.
- API client → State fn: invokes · Calls the series-state function through the Netlify runtime.
- API client → Search fn: invokes · Calls the series-search function through the Netlify runtime.
- Session fn → HTTP utils: uses · Shares request/response helpers.
- Session fn → Env utils: uses · Reads access configuration.
- Session fn → Access utils: uses · Validates access keys and sessions.
- State fn → HTTP utils: uses · Shares request/response helpers.
- State fn → Env utils: uses · Reads persistence configuration.
- State fn → Access utils: uses · Checks private access before writes.
- State fn → Series shared: uses · Normalizes and validates series data.
- Search fn → HTTP utils: uses · Shares request/response helpers.
- Search fn → Env utils: uses · Reads external API configuration.
- Search fn → Series shared: uses · Normalizes series-shaped records.
- Search fn → Metadata lib: uses · Runs the enrichment/search pipeline.
- Form state → Series types: uses · Consumes the shared series record shape.
- JSON transfer → Seed JSON: imports · Supports JSON transfer of the sample snapshot.
- Vite build → Main: builds · Bundles the browser entry and app code.
- Netlify config → Session fn: wires · Exposes the function at runtime.
- Netlify config → State fn: wires · Exposes the function at runtime.
- Netlify config → Search fn: wires · Exposes the function at runtime.
- Vitest → Collection hook: covers · Validates domain workflow behavior.
- Vitest → Series form: covers · Validates form behavior.
- Vitest → App shell: covers · Validates shell integration.
