Docs: Update all documentation for series loading and episode tracking fixes

docs/ARCHITECTURE.md

@@ -31,8 +31,10 @@ Aniworld is a web-based anime download manager built with Python, FastAPI, and S
 +--------v---------+     +--------v---------+
 |                  |     |                  |
 |   SQLite DB      |     |   File System    |
-|   (aniworld.db)  |     |   (data/*.json)  |
-|                  |     |                  |
+|   (aniworld.db)  |     |   (anime/*/)     |
+|  - Series data   |     |   - Video files  |
+|  - Episodes      |     |   - NFO files    |
+|  - Queue state   |     |   - Media files  |
 +------------------+     +------------------+
 ```
 

docs/CHANGELOG.md

@@ -35,6 +35,30 @@ This document tracks all notable changes to the Aniworld project.
 
 This changelog follows [Keep a Changelog](https://keepachangelog.com/) principles and adheres to [Semantic Versioning](https://semver.org/).
 
+---
+
+## [Unreleased] - 2026-01-18
+
+### Fixed
+
+- **Series Visibility**: Fixed issue where series added to the database weren't appearing in the API/UI
+  - Series are now loaded from database into SeriesApp's in-memory cache on startup
+  - Added `_load_series_from_db()` call after initial database sync in FastAPI lifespan
+- **Episode Tracking**: Fixed missing episodes not being saved to database when adding new series
+  - Missing episodes are now persisted to the `episodes` table after the targeted scan
+  - Episodes are properly synced during rescan operations (added/removed based on filesystem state)
+- **Database Synchronization**: Improved data consistency between database and in-memory cache
+  - Rescan process properly updates episodes: adds new missing episodes, removes downloaded ones
+  - All series operations now maintain database and cache synchronization
+
+### Technical Details
+
+- Modified `src/server/fastapi_app.py` to load series from database after sync
+- Modified `src/server/api/anime.py` to save scanned episodes to database
+- Episodes table properly tracks missing episodes with automatic cleanup
+
+---
+
 ## Sections for Each Release
 
 ```markdown

docs/DATABASE.md

@@ -81,7 +81,10 @@ Source: [src/server/database/models.py](../src/server/database/models.py#L23-L87
 
 ### 3.2 episodes
 
-Stores individual episode information.
+Stores **missing episodes** that need to be downloaded. Episodes are automatically managed during scans:
+- New missing episodes are added to the database
+- Episodes that are no longer missing (files now exist) are removed from the database
+- When an episode is downloaded, it can be marked with `is_downloaded=True` or removed from tracking
 
 | Column           | Type          | Constraints                  | Description                   |
 | ---------------- | ------------- | ---------------------------- | ----------------------------- |

docs/features.md

@@ -59,9 +59,12 @@ The application now features a comprehensive configuration system that allows us
 ## Anime Management
 
 - **Anime Library Page**: Display list of anime series with missing episodes
+- **Database-Backed Series Storage**: All series metadata and missing episodes stored in SQLite database
+- **Automatic Database Synchronization**: Series loaded from database on startup, stays in sync with filesystem
 - **Series Selection**: Select individual anime series and add episodes to download queue
 - **Anime Search**: Search for anime series using integrated providers
-- **Library Scanning**: Automated scanning for missing episodes
+- **Library Scanning**: Automated scanning for missing episodes with database persistence
+- **Episode Tracking**: Missing episodes tracked in database, automatically updated during scans
 - **NFO Status Indicators**: Visual badges showing NFO and media file status for each series
 
 ## NFO Metadata Management

docs/instructions.md

@@ -120,3 +120,9 @@ For each task completed:
 ## TODO List:
 
 1. ✅ **COMPLETED**: SeriesApp no longer loads series from data files on every startup. Series are now loaded once during setup via `sync_series_from_data_files()` in the FastAPI lifespan. The `SeriesApp` initializes with `skip_load=True` passed to `SerieList`, preventing automatic file loading. Subsequent operations load series from the database through the service layer.
+
+2. ✅ **COMPLETED**: Fixed series visibility and episode tracking:
+   - Series from database are now loaded into SeriesApp's in-memory cache on startup
+   - Missing episodes are saved to database when adding new series
+   - Rescan process properly updates episodes in database (adds new, removes downloaded)
+   - Database stays in sync with filesystem state