How estudiagit/mis-series works
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: useSeriesCollection.ts Collection hook · App.tsx App shell · series-state.mjs State fn · series-search.mjs Search fn
Components 32
Client app
React UI, hooks, and browser-side services.
- Main · Vite entry that mounts the app.
src/main.tsx - App shell · Top-level React composition and routing of the UI.
src/App.tsx - Access gate · Locked/unlocked app boundary in the browser.
src/components/AccessGate.tsx - Header · Top-level series page header and controls.
src/components/SeriesHeader.tsx - Series list · Collection viewport for rendering and interacting with series.
src/components/SeriesList.tsx - Series card · Single series row/card representation and actions.
src/components/SeriesCard.tsx - Series form · Create/edit form for series records.
src/components/SeriesForm.tsx - Options menu · Per-item actions and overflow controls.
src/components/SeriesOptionsMenu.tsx - Toast · Transient client feedback notifications.
src/components/Toast.tsx - Access state · Client access-state coordination and unlock flow.
src/hooks/useAppAccess.ts - Collection hook · Main browser-side series workflow orchestration.
src/hooks/useSeriesCollection.ts - Filters · Search and filter state for the series collection.
src/hooks/useSeriesFilters.ts - Form state · Create/edit form state and validation coordination.
src/hooks/useSeriesFormState.ts - Drag and drop · Ordering interactions for reordering series.
src/hooks/useSeriesDragAndDrop.ts - JSON transfer · Import/export of series snapshots via JSON.
src/hooks/useSeriesJsonTransfer.ts - API client · Shared HTTP transport abstraction for function calls.
src/services/apiClient.ts - Access service · Client endpoint wrapper for session/access handling.
src/services/accessService.ts - Series service · Client endpoint wrapper for reading and writing series state.
src/services/seriesStateService.ts - Metadata service · Client endpoint wrapper for series search and metadata lookups.
src/services/seriesMetadataService.ts
Netlify backend
Functions and shared server-side helpers.
- Session fn · Creates or validates an authenticated session.
netlify/functions/session.mjs - State fn · Private series list read/write API backed by Blobs.
netlify/functions/series-state.mjs - Search fn · Series search and metadata lookup API.
netlify/functions/series-search.mjs - HTTP utils · Shared request/response helpers for functions.
netlify/functions/_lib/http.mjs - Env utils · Environment loading and configuration helpers.
netlify/functions/_lib/env.mjs - Access utils · Server-side access-key validation and auth helpers.
netlify/functions/_lib/access.mjs - Series shared · Series normalization and shared backend domain helpers.
netlify/functions/_lib/series-shared.mjs - Metadata lib · TVMaze/Gemini enrichment pipeline helpers.
netlify/functions/_lib/series-metadata.mjs
Shared domain
Common types and transfer assets.
- Series types · Shared series entity shape used across the app.
src/types.ts - Seed JSON · Importable/exportable sample series snapshot.
public/mis_series.json
Tooling
Build, test, and deployment runtime.
- Vite build · Frontend bundling and dev server build toolchain.
vite.config.ts - Netlify config · Local and production function/runtime wiring.
netlify.toml - Vitest · Unit and component test harness.
vitest.config.ts
Connections 43
- 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.