From 56190ff3bbef7f86643673ab7af1d6f4370b7068 Mon Sep 17 00:00:00 2001
From: AlkenD <desteralken@gmail.com>
Date: Mon, 27 Oct 2025 04:10:17 +0530
Subject: [PATCH 1/2] chore: update documentation

---
 .github/workflows/deploy-docs.yml             |  64 +++
 CONTRIBUTING.md                               | 456 ++----------------
 README.md                                     | 155 +++---
 apps/docs/astro.config.mjs                    |  17 +-
 apps/docs/src/content/docs/api/overview.md    |  17 +-
 apps/docs/src/content/docs/clients/flutter.md | 292 +++++++++++
 .../docs/src/content/docs/clients/overview.md | 126 +++++
 .../content/docs/development/contributing.md  |  13 +-
 .../content/docs/development/versioning.md    | 141 +++++-
 9 files changed, 746 insertions(+), 535 deletions(-)
 create mode 100644 .github/workflows/deploy-docs.yml
 create mode 100644 apps/docs/src/content/docs/clients/flutter.md
 create mode 100644 apps/docs/src/content/docs/clients/overview.md

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 0000000..848a8bf
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,64 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'apps/docs/**'
+      - '.github/workflows/deploy-docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: 'pnpm'
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build docs
+        run: |
+          cd apps/docs
+          pnpm build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: apps/docs/dist
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bb3e65f..37c5f35 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -2,461 +2,59 @@
 
 Thank you for your interest in contributing to DesterLib! 🎉
 
-We welcome contributions from the community. This guide will help you get started.
+## 📖 Documentation
 
-## Table of Contents
+All contribution guidelines are maintained in the **DesterLib Documentation**:
 
-- [Code of Conduct](#code-of-conduct)
-- [Getting Started](#getting-started)
-- [Development Setup](#development-setup)
-- [How to Contribute](#how-to-contribute)
-- [Pull Request Process](#pull-request-process)
-- [Commit Guidelines](#commit-guidelines)
-- [Changeset Guidelines](#changeset-guidelines)
-- [Need Help?](#need-help)
+👉 **[View Contributing Guide](https://desterlib.github.io/desterlib/development/contributing)**
 
-## Code of Conduct
+The documentation covers:
+- **General Guidelines** - Commit conventions, versioning, PR process (applies to all projects)
+- **API Server Development** - Backend development setup
+- **Client Development** - Mobile, desktop, and TV app development
+- **Code Standards** - Style guides and best practices
 
-We are committed to providing a welcoming and inspiring community for all. By participating in this project, you agree to:
-
-- Be respectful and inclusive
-- Be patient and welcoming
-- Be considerate of different viewpoints
-- Focus on what's best for the community
-- Show empathy towards other community members
-
-**Unacceptable behavior includes:**
-- Harassment, trolling, or discriminatory language
-- Personal attacks or insults
-- Publishing others' private information
-- Other conduct inappropriate in a professional setting
-
-Instances of unacceptable behavior may result in a temporary or permanent ban from the project.
-
-## Getting Started
-
-### Prerequisites
-
-Before contributing, make sure you have:
-
-- **Node.js** 18 or higher
-- **pnpm** 9.0.0 or higher
-- **Docker** (for testing database)
-- **Git** for version control
-- A **GitHub account**
-
-### Find an Issue to Work On
-
-1. Check [open issues](https://github.com/DesterLib/desterlib/issues)
-2. Look for issues labeled `good first issue` or `help wanted`
-3. Comment on the issue you want to work on
-4. Wait for maintainer approval before starting work
-
-**Not sure where to start?**
-- Look for `good first issue` labels
-- Fix typos or improve documentation
-- Report bugs you've found
-- Suggest new features in discussions
-
-## Development Setup
-
-### 1. Fork the Repository
-
-Click the "Fork" button at the top right of the [DesterLib repository](https://github.com/DesterLib/desterlib).
-
-### 2. Clone Your Fork
+## 🚀 Quick Start
 
 ```bash
-# Clone your fork
+# 1. Fork and clone
 git clone https://github.com/YOUR-USERNAME/desterlib.git
 cd desterlib
 
-# Add upstream remote
-git remote add upstream https://github.com/DesterLib/desterlib.git
-```
-
-### 3. Install Dependencies
-
-```bash
-# Install all dependencies
+# 2. Install dependencies
 pnpm install
-```
-
-### 4. Set Up Development Database
 
-```bash
-# Start test database with Docker
+# 3. Start database
 docker-compose -f docker-compose.test.yml up -d
 
-# Push database schema
-cd apps/api
-pnpm db:push
-```
-
-### 5. Start Development Server
-
-```bash
-# From repository root
-pnpm dev
-
-# Or run specific app
+# 4. Start API
 cd apps/api
 pnpm dev
-```
-
-The API will be available at `http://localhost:3001`
-
-### 6. Verify Setup
-
-- Visit `http://localhost:3001/api/docs` for Swagger documentation
-- Try making a test API request
 
-## How to Contribute
-
-### Workflow Overview
-
-```
-Fork → Clone → Create Branch → Make Changes → Commit → Push → Pull Request
-```
-
-### Step-by-Step Process
-
-#### 1. Sync with Upstream
-
-Always sync with the latest changes before starting new work:
-
-```bash
-# Fetch latest changes from upstream
-git fetch upstream
-
-# Switch to dev branch
-git checkout dev
-
-# Merge upstream changes
-git merge upstream/dev
-
-# Push to your fork
-git push origin dev
-```
-
-#### 2. Create a Feature Branch
-
-```bash
-# Create branch from dev
-git checkout dev
-git checkout -b feat/your-feature-name
-
-# For bug fixes
-git checkout -b fix/bug-description
-
-# For documentation
-git checkout -b docs/what-you-update
-```
-
-**Branch naming conventions:**
-- `feat/feature-name` - New features
-- `fix/bug-name` - Bug fixes
-- `docs/update-name` - Documentation updates
-- `refactor/what-changed` - Code refactoring
-- `perf/improvement-name` - Performance improvements
-- `test/test-name` - Test additions/updates
-
-#### 3. Make Your Changes
-
-- Write clean, readable code
-- Follow existing code style
-- Add comments for complex logic
-- Update documentation if needed
-- Add tests for new features
-
-#### 4. Test Your Changes
-
-```bash
-# Run linter
-pnpm lint
-
-# Check types
-pnpm check-types
-
-# Run tests (when available)
-pnpm test
-
-# Build to verify no errors
-pnpm build
-```
-
-#### 5. Commit Your Changes
-
-We use **conventional commits** for consistent commit messages:
-
-```bash
-# Use the interactive commit tool (recommended)
+# 5. Make commits
 pnpm commit
 
-# This will guide you through:
-# - Type (feat, fix, docs, etc.)
-# - Scope (api, database, etc.)
-# - Description
-# - Body (optional)
-# - Breaking changes (if any)
-```
-
-**Manual commit format:**
-```
-<type>(<scope>): <description>
-
-[optional body]
-
-[optional footer]
-```
-
-**Examples:**
-```bash
-feat(api): add user search endpoint
-fix(stream): resolve buffering issue on Safari
-docs: update installation guide
-refactor(database): simplify query logic
-```
-
-See [Commit Guidelines](apps/docs/src/content/docs/development/commit-guidelines.md) for more details.
-
-#### 6. Create a Changeset
-
-If your changes affect users (new features, bug fixes, breaking changes), create a changeset:
-
-```bash
-# Create changeset
+# 6. Add changeset (for user-facing changes)
 pnpm changeset
 
-# Follow the prompts:
-# 1. Select affected packages (usually 'api')
-# 2. Choose bump type (patch/minor/major)
-# 3. Write a summary (appears in changelog)
-```
-
-**When to create a changeset:**
-- ✅ New features
-- ✅ Bug fixes
-- ✅ Breaking changes
-- ✅ Performance improvements
-- ✅ Dependency updates affecting users
-
-**When to skip changesets:**
-- ❌ Documentation updates
-- ❌ Internal refactoring
-- ❌ Test additions
-- ❌ CI/CD changes
-
-**Commit the changeset:**
-```bash
-git add .changeset/
-git commit -m "chore: add changeset"
+# 7. Push and create PR
 ```
 
-#### 7. Push to Your Fork
-
-```bash
-# Push your branch to your fork
-git push origin feat/your-feature-name
-```
-
-## Pull Request Process
-
-### Creating a Pull Request
-
-1. Go to [DesterLib repository](https://github.com/DesterLib/desterlib)
-2. Click "Pull requests" → "New pull request"
-3. Click "compare across forks"
-4. Select:
-   - **base repository:** `DesterLib/desterlib`
-   - **base branch:** `dev`
-   - **head repository:** `YOUR-USERNAME/desterlib`
-   - **compare branch:** `feat/your-feature-name`
-5. Click "Create pull request"
-6. Fill out the PR template completely
-7. Click "Create pull request"
-
-### PR Checklist
-
-Before submitting, ensure:
-
-- [ ] Code follows project style guidelines
-- [ ] Self-reviewed your own code
-- [ ] Commented complex code sections
-- [ ] Updated documentation if needed
-- [ ] No new warnings generated
-- [ ] Added changeset (if user-facing changes)
-- [ ] Used conventional commits
-- [ ] Tests pass (when available)
-- [ ] Linter passes: `pnpm lint`
-- [ ] Type check passes: `pnpm check-types`
-
-### PR Review Process
-
-1. **Automated Checks:** GitHub Actions will run:
-   - Changeset validation
-   - Linting
-   - Type checking
-   - Build verification
-
-2. **Code Review:** Maintainers will review your PR:
-   - Provide feedback and suggestions
-   - Request changes if needed
-   - Approve when ready
-
-3. **Address Feedback:**
-   ```bash
-   # Make requested changes
-   git add .
-   pnpm commit
-   git push origin feat/your-feature-name
-   # PR updates automatically
-   ```
-
-4. **Merge:** Once approved, a maintainer will merge your PR to `dev`
-
-### After Your PR is Merged
-
-1. Sync your fork:
-   ```bash
-   git checkout dev
-   git pull upstream dev
-   git push origin dev
-   ```
-
-2. Delete your feature branch:
-   ```bash
-   git branch -d feat/your-feature-name
-   git push origin --delete feat/your-feature-name
-   ```
-
-3. Celebrate! 🎉 You've contributed to DesterLib!
-
-## Commit Guidelines
-
-### Commit Types
-
-| Type | Description | Example |
-|------|-------------|---------|
-| `feat` | New feature | `feat(api): add user search` |
-| `fix` | Bug fix | `fix(auth): resolve JWT error` |
-| `docs` | Documentation | `docs: update README` |
-| `style` | Code style | `style: format with prettier` |
-| `refactor` | Code refactoring | `refactor: simplify query` |
-| `perf` | Performance | `perf: optimize caching` |
-| `test` | Tests | `test: add auth tests` |
-| `build` | Build system | `build: update deps` |
-| `ci` | CI/CD | `ci: add workflow` |
-| `chore` | Other changes | `chore: update gitignore` |
-
-### Available Scopes
-
-`api`, `database`, `websocket`, `stream`, `library`, `movies`, `tvshows`, `scan`, `settings`, `auth`, `middleware`, `config`, `deps`, `docker`, `ci`, `docs`, `release`
+## 📚 Additional Resources
 
-### Breaking Changes
+- [API Server Overview](https://desterlib.github.io/desterlib/api/overview) - Backend development
+- [Client Overview](https://desterlib.github.io/desterlib/clients/overview) - Client development
+- [Project Structure](https://desterlib.github.io/desterlib/development/structure) - Codebase organization
+- [Commit Guidelines](https://desterlib.github.io/desterlib/development/commit-guidelines) - Commit conventions
+- [Versioning Guide](https://desterlib.github.io/desterlib/development/versioning) - Version management
 
-If introducing breaking changes:
+## 💬 Need Help?
 
-1. Add `!` after type/scope:
-   ```
-   feat(api)!: redesign authentication
-   ```
-
-2. Add `BREAKING CHANGE:` in footer:
-   ```
-   feat(api)!: redesign authentication
-   
-   BREAKING CHANGE: /auth/login endpoint removed.
-   Use OAuth2 flow instead.
-   ```
-
-3. Create changeset with **major** bump
-
-## Changeset Guidelines
-
-### Semantic Versioning
-
-We follow [Semantic Versioning](https://semver.org/):
-
-- **Patch (0.0.X)** - Bug fixes, small changes
-- **Minor (0.X.0)** - New features (backward-compatible)
-- **Major (X.0.0)** - Breaking changes
-
-### Creating Effective Changesets
-
-**Good changeset summary:**
-```
-Add WebSocket support for real-time notifications
-
-- New /ws endpoint for WebSocket connections
-- Real-time event streaming
-- Connection management utilities
-```
-
-**Bad changeset summary:**
-```
-updates
-```
-
-The changeset summary becomes the changelog entry that users read. Make it descriptive!
-
-## Development Tips
-
-### Code Style
-
-- Use TypeScript strict mode
-- Follow existing patterns in the codebase
-- Keep functions small and focused
-- Use meaningful variable names
-- Add JSDoc comments for public APIs
-
-### Testing
-
-- Test your changes thoroughly
-- Test edge cases
-- Test error conditions
-- Verify existing functionality still works
-
-### Documentation
-
-- Update docs for new features
-- Add code comments for complex logic
-- Update README if user-facing changes
-- Include examples in docs
-
-## Project Structure
-
-```
-desterlib/
-├── apps/
-│   ├── api/          # Backend API (Express + TypeScript)
-│   └── docs/         # Documentation site (Starlight)
-├── packages/
-│   ├── eslint-config/       # Shared ESLint config
-│   └── typescript-config/   # Shared TypeScript config
-└── .changeset/       # Version management
-```
-
-See [Project Structure](apps/docs/src/content/docs/development/structure.md) for details.
-
-## Need Help?
-
-- 📖 [Documentation](http://localhost:4321) (run `cd apps/docs && pnpm dev`)
-- 💬 [GitHub Discussions](https://github.com/DesterLib/desterlib/discussions)
 - 🐛 [Report Issues](https://github.com/DesterLib/desterlib/issues)
-- 📧 Contact maintainers through GitHub
-
-## Recognition
-
-All contributors will be recognized in our README and release notes. Thank you for helping make DesterLib better! ❤️
+- 💬 [GitHub Discussions](https://github.com/DesterLib/desterlib/discussions)
+- 📖 [Documentation](https://desterlib.github.io/desterlib)
+- 📚 [API Docs](http://localhost:3001/api/docs) (when running locally)
 
 ## License
 
-By contributing to DesterLib, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
-
-This means:
-- Your contributions will remain open source
-- Derivatives must also be open source under AGPL-3.0
-- Network use of the software requires source code sharing
-- This protects the community and ensures DesterLib stays free and open
-
+By contributing, you agree that your contributions will be licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
diff --git a/README.md b/README.md
index 0f9584a..2ba87ba 100644
--- a/README.md
+++ b/README.md
@@ -1,96 +1,83 @@
 # 🎬 DesterLib
 
-**Your Personal Media Server** - Watch your movies and TV shows from anywhere. It's like Netflix, but for YOUR personal collection!
+**Your Personal Media Server** - Self-hosted media streaming for movies and TV shows.
 
 [![GitHub](https://img.shields.io/badge/GitHub-DesterLib-blue?logo=github)](https://github.com/DesterLib/desterlib)
 [![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-desterlib-blue)](https://desterlib.github.io/desterlib)
 
 ---
 
 ## What is DesterLib?
 
-DesterLib is a modern, self-hosted media server system that lets you:
+DesterLib is a modern, self-hosted media server that lets you:
 - 📚 **Organize** your media collection automatically
 - 🎞️ **Stream** movies and TV shows smoothly
-- 📱 **Watch** on any device (Android, iOS, macOS, Linux, Windows)
-- ⚙️ **Control** your entire media library from one place
+- 📱 **Watch** on any device (mobile, desktop, TV)
+- 🎨 **Beautiful UI** with automatic metadata and artwork
 
----
+**Components:**
+- **API Server** (this repo) - Backend for media management and streaming
+- **Client Apps** - Mobile and desktop applications ([desterlib-flutter](https://github.com/DesterLib/desterlib-flutter))
 
-## Quick Start
+---
 
-### Prerequisites
-- Docker installed
-- Node.js 18+ and pnpm (for development)
-- Your media files
+## 🚀 Quick Start
 
-### Development Setup
+### Using Docker (Recommended)
 
 ```bash
 # Clone the repository
 git clone https://github.com/DesterLib/desterlib.git
 cd desterlib
 
-# Start test database
-docker-compose -f docker-compose.test.yml up -d
+# Start all services
+docker-compose up -d
 
-# Install dependencies and run
-pnpm install
-cd apps/api
-pnpm dev
+# Access API: http://localhost:3001
+# API Docs: http://localhost:3001/api/docs
 ```
 
-Access the API at `http://localhost:3001`
-
-### Production Setup
+### Development Setup
 
 ```bash
-# Start all services with Docker
-docker-compose up -d
+# Install dependencies
+pnpm install
+
+# Start test database
+docker-compose -f docker-compose.test.yml up -d
+
+# Run API server
+cd apps/api
+pnpm dev
 ```
 
 ---
 
 ## 📚 Documentation
 
-**Full documentation is available at: http://localhost:4321**
-
-To run the docs locally:
-```bash
-cd apps/docs
-pnpm dev
-```
+**📖 Full Documentation:** [desterlib.github.io/desterlib](https://desterlib.github.io/desterlib)
 
 ### Quick Links
 
-- 📥 [Download Flutter App](https://github.com/DesterLib/Dester-Flutter/releases/latest) - Get the alpha client app
-- 🚀 [Quick Start Guide](http://localhost:4321/getting-started/quick-start/) - Get up and running
-- 📦 [Installation Guide](http://localhost:4321/getting-started/installation/) - Detailed setup
-- 🏗️ [Project Structure](http://localhost:4321/development/structure/) - Code organization
-- 📋 [Versioning Guide](http://localhost:4321/development/versioning/) - Contributing
-- 💻 [Commit Guidelines](http://localhost:4321/development/commit-guidelines/) - Commit format
-- 🔗 [API Documentation](http://localhost:3001/api/docs) - When API is running
+- [Getting Started](https://desterlib.github.io/desterlib/getting-started/quick-start) - Installation and setup
+- [API Server Guide](https://desterlib.github.io/desterlib/api/overview) - Backend development
+- [Client Apps](https://desterlib.github.io/desterlib/clients/overview) - Mobile & desktop apps
+- [Contributing](https://desterlib.github.io/desterlib/development/contributing) - How to contribute
+- [API Docs](http://localhost:3001/api/docs) - Interactive API documentation (when running)
 
 ---
 
-## Contributing
-
-We welcome contributions from the community! 🎉
+## 🤝 Contributing
 
-### Quick Start for Contributors
+We welcome contributions! Please see our [Contributing Guide](https://desterlib.github.io/desterlib/development/contributing).
 
+**Quick Start:**
 ```bash
-# Fork the repo, then:
-git clone https://github.com/YOUR-USERNAME/desterlib.git
-cd desterlib
-
-# Install dependencies
-pnpm install
-
-# Create feature branch
+# Fork, clone, and create branch
 git checkout -b feat/your-feature
 
-# Make changes and commit
+# Make changes with conventional commits
 pnpm commit
 
 # Add changeset for user-facing changes
@@ -100,75 +87,53 @@ pnpm changeset
 git push origin feat/your-feature
 ```
 
-### Branching Strategy
-
-- `main` → Production releases (tagged)
-- `dev` → Development (merge PRs here)
-- `feat/*` → New features
-- `fix/*` → Bug fixes
-- `docs/*` → Documentation updates
-
-### Resources
-
-- 📖 **[Contributing Guide](CONTRIBUTING.md)** - Complete contribution instructions
-- 💻 **[Commit Guidelines](http://localhost:4321/development/commit-guidelines/)** - Commit message format
-- 🦋 **[Versioning Guide](http://localhost:4321/development/versioning/)** - Changesets workflow
-- 📋 **[Quick Reference](http://localhost:4321/development/quick-reference/)** - Common commands
-
-**Before submitting a PR:**
-1. Use conventional commits: `pnpm commit`
-2. Add changeset: `pnpm changeset` (if needed)
-3. Ensure tests pass: `pnpm lint && pnpm check-types`
-4. Fill out the PR template completely
+**Resources:**
+- [Contributing Guide](CONTRIBUTING.md) - Quick start
+- [Commit Guidelines](https://desterlib.github.io/desterlib/development/commit-guidelines)
+- [Versioning Guide](https://desterlib.github.io/desterlib/development/versioning)
 
 ---
 
-## Project Structure
+## 🏗️ Project Structure
 
 ```
 desterlib/
 ├── apps/
-│   ├── api/          # Backend API (Express + TypeScript)
-│   └── docs/         # Documentation site (Starlight)
-├── packages/
-│   ├── eslint-config/       # Shared ESLint config
-│   └── typescript-config/   # Shared TypeScript config
-└── .changeset/       # Version management
+│   ├── api/          # Backend API (Node.js + TypeScript + Express)
+│   └── docs/         # Documentation (Astro + Starlight)
+└── packages/
+    ├── eslint-config/       # Shared ESLint configuration
+    └── typescript-config/   # Shared TypeScript configuration
 ```
 
 ---
 
-## Key Features
+## 📦 Features
 
-✅ Automatic media scanning and organization  
-✅ Smooth video streaming  
-✅ Multi-device support  
-✅ REST API with WebSocket support  
-✅ Docker-ready deployment  
-✅ Cross-platform (Android, iOS, Desktop)
+- ✅ Automatic media scanning and organization
+- ✅ TMDB metadata and artwork integration
+- ✅ Video streaming with transcoding support
+- ✅ Watch progress tracking
+- ✅ REST API + WebSocket support
+- ✅ Docker-ready deployment
+- ✅ Cross-platform clients (Android, iOS, macOS, Linux, Windows)
 
 ---
 
-## Get Help
+## 💬 Support
 
-- 📖 [Documentation](http://localhost:4321)
+- 📖 [Documentation](https://desterlib.github.io/desterlib)
 - 🐛 [Report Issues](https://github.com/DesterLib/desterlib/issues)
 - 💬 [Discussions](https://github.com/DesterLib/desterlib/discussions)
 
 ---
 
-## License
-
-**GNU Affero General Public License v3.0 (AGPL-3.0)**
+## 📄 License
 
-DesterLib is free and open source software licensed under AGPL-3.0. This ensures:
-- The software remains free forever
-- All modifications must be open source
-- Network use requires source code sharing
-- No proprietary forks allowed
+GNU Affero General Public License v3.0 (AGPL-3.0)
 
-See [LICENSE](LICENSE) for full details.
+This ensures the software remains free and open source forever. See [LICENSE](LICENSE) for details.
 
 ---
 
-**Happy watching! 🎉**
+**Made with ❤️ by the DesterLib community**
diff --git a/apps/docs/astro.config.mjs b/apps/docs/astro.config.mjs
index 6c84e38..9d2474c 100644
--- a/apps/docs/astro.config.mjs
+++ b/apps/docs/astro.config.mjs
@@ -4,6 +4,8 @@ import starlight from '@astrojs/starlight';
 
 // https://astro.build/config
 export default defineConfig({
+	site: 'https://desterlib.github.io',
+	base: '/desterlib',
 	integrations: [
 		starlight({
 			title: 'DesterLib Docs',
@@ -24,8 +26,22 @@ export default defineConfig({
 						{ label: 'Installation', slug: 'getting-started/installation' },
 					],
 				},
+				{
+					label: 'Projects',
+					items: [
+						{ label: 'API Server', slug: 'api/overview' },
+						{ label: 'Client Applications', slug: 'clients/overview' },
+					],
+				},
+				{
+					label: 'Client Platforms',
+					items: [
+						{ label: 'Platform Setup', slug: 'clients/flutter' },
+					],
+				},
 				{
 					label: 'Development',
+					collapsed: false,
 					items: [
 						{ label: 'Contributing Guide', slug: 'development/contributing' },
 						{ label: 'Project Structure', slug: 'development/structure' },
@@ -37,7 +53,6 @@ export default defineConfig({
 				{
 					label: 'API Reference',
 					items: [
-						{ label: 'Overview', slug: 'api/overview' },
 						{ label: 'Swagger Docs', link: 'http://localhost:3001/api/docs', attrs: { target: '_blank', rel: 'noopener noreferrer' } },
 					],
 				},
diff --git a/apps/docs/src/content/docs/api/overview.md b/apps/docs/src/content/docs/api/overview.md
index 3428590..ef45311 100644
--- a/apps/docs/src/content/docs/api/overview.md
+++ b/apps/docs/src/content/docs/api/overview.md
@@ -1,9 +1,20 @@
 ---
-title: API Overview
-description: DesterLib REST API documentation and reference
+title: API Server
+description: DesterLib API Server - Backend for your personal media library
 ---
 
-DesterLib provides a comprehensive REST API for managing your media library, streaming content, and integrating with other applications.
+The DesterLib API Server is the backend that powers your personal media library. It provides a comprehensive REST API for managing your media library, streaming content, and integrating with client applications.
+
+## What is the API Server?
+
+The API Server handles:
+- **Media Library Management** - Scan, organize, and index your media files
+- **Metadata Fetching** - Automatic metadata and artwork from TMDB
+- **Video Streaming** - Adaptive streaming endpoints
+- **Watch Progress** - Track viewing history and resume points
+- **WebSocket Events** - Real-time updates for scans and library changes
+
+**Repository**: [desterlib](https://github.com/DesterLib/desterlib) (monorepo)
 
 ## Interactive API Documentation
 
diff --git a/apps/docs/src/content/docs/clients/flutter.md b/apps/docs/src/content/docs/clients/flutter.md
new file mode 100644
index 0000000..c386a84
--- /dev/null
+++ b/apps/docs/src/content/docs/clients/flutter.md
@@ -0,0 +1,292 @@
+---
+title: Platform Setup
+description: Platform-specific setup and development guide for the Dester client
+---
+
+The Dester client is a cross-platform application for browsing and streaming your DesterLib media collection. This guide covers platform-specific setup and development.
+
+## 📱 Supported Platforms
+
+### Available Now
+- **Android** - Phones and tablets (SDK 21+)
+- **iOS** - iPhone and iPad (iOS 12.0+)
+- **macOS** - Desktop application (10.14+)
+- **Linux** - Desktop application (Ubuntu 20.04+)
+- **Windows** - Desktop application (Windows 10+)
+
+### In Development
+- **Android TV** - TV interface with remote control support
+- **Apple TV / tvOS** - Native TV experience
+
+## 🚀 Getting Started
+
+### Prerequisites
+
+- Flutter SDK 3.9.2 or higher
+- DesterLib API server running
+- Platform-specific development tools (Android Studio, Xcode, etc.)
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/DesterLib/desterlib-flutter.git
+cd desterlib-flutter
+
+# Install dependencies
+flutter pub get
+
+# Generate code
+dart run build_runner build --delete-conflicting-outputs
+
+# Run the app
+flutter run
+```
+
+### Server Configuration
+
+On first launch, configure your DesterLib API server:
+
+1. Open **Settings** → **Server Configuration**
+2. Enter your server URL:
+   - Local: `http://localhost:3001`
+   - Network: `http://192.168.1.XXX:3001`
+   - Remote: `https://yourdomain.com`
+3. Save and the app will connect automatically
+
+## 🏗️ Architecture
+
+### Tech Stack
+
+The client is built with Flutter, providing native performance across all platforms:
+
+- **Flutter SDK** - Cross-platform UI framework
+- **Riverpod** - State management
+- **go_router** - Navigation and routing
+- **media_kit** - Video playback
+- **OpenAPI** - Auto-generated API client
+
+### Project Structure
+
+```
+lib/
+├── main.dart              # App entry point
+├── app/
+│   ├── router.dart        # Navigation configuration
+│   ├── theme/             # App theming
+│   └── providers.dart     # Global providers
+├── features/              # Feature modules
+│   ├── home/              # Home screen
+│   ├── library/           # Library browsing
+│   ├── media/             # Media detail pages
+│   └── settings/          # Settings and configuration
+├── shared/
+│   ├── widgets/           # Reusable UI components
+│   ├── utils/             # Utility functions
+│   └── providers/         # Shared state providers
+└── api/                   # Generated API client
+```
+
+## 🎨 Features
+
+### Media Browsing
+
+- Browse movies and TV shows
+- Search functionality
+- Filter by genre, year, rating
+- Sort options
+- Grid and list views
+
+### Video Player
+
+- Smooth streaming playback
+- Playback controls (play, pause, seek)
+- Volume control
+- Fullscreen support
+- Playback speed adjustment
+- Subtitle support (coming soon)
+- Audio track selection (coming soon)
+
+### Watch Progress
+
+- Automatic progress tracking
+- Resume from where you left off
+- Mark as watched/unwatched
+- Watch history
+
+### Settings
+
+- Server configuration
+- Theme selection (light/dark)
+- Playback preferences
+- Cache management
+- About and version info
+
+## 🔧 Development
+
+### Contributing
+
+See the [contributing guide](https://github.com/DesterLib/desterlib-flutter/blob/main/CONTRIBUTING.md) for development setup.
+
+All contribution guidelines (commits, versioning, etc.) follow the main DesterLib standards documented in this site.
+
+### Building for Release
+
+#### Android
+
+```bash
+# APK
+flutter build apk --release
+
+# App Bundle (for Play Store)
+flutter build appbundle --release
+```
+
+#### iOS
+
+```bash
+# Build for iOS
+flutter build ios --release
+
+# Open in Xcode for deployment
+open ios/Runner.xcworkspace
+```
+
+#### Desktop
+
+```bash
+# macOS
+flutter build macos --release
+
+# Linux
+flutter build linux --release
+
+# Windows
+flutter build windows --release
+```
+
+### Testing
+
+```bash
+# Run all tests
+flutter test
+
+# Run tests with coverage
+flutter test --coverage
+
+# Run specific test file
+flutter test test/features/player_test.dart
+```
+
+### Code Quality
+
+```bash
+# Analyze code
+flutter analyze
+
+# Format code
+dart format lib/
+
+# Run linter
+flutter analyze --fatal-infos
+```
+
+## 🎯 Roadmap
+
+### Current Focus
+
+- [ ] **TV Platform Support** - Android TV and Apple TV
+- [ ] **Subtitle Support** - SRT, VTT formats
+- [ ] **Audio Track Selection** - Multiple audio streams
+- [ ] **Offline Downloads** - Save for offline viewing
+
+### Future Plans
+
+- [ ] **Chromecast** - Cast to any TV
+- [ ] **Picture-in-Picture** - Watch while using other apps
+- [ ] **Widgets** - Quick access shortcuts
+- [ ] **Multi-User Profiles** - Separate watch history
+- [ ] **Parental Controls** - Content restrictions
+
+## 📱 Platform-Specific Notes
+
+### Android
+
+- Minimum SDK: 21 (Android 5.0)
+- Target SDK: 34 (Android 14)
+- Uses ExoPlayer for video playback
+
+### iOS
+
+- Minimum version: iOS 12.0
+- Uses AVPlayer for video playback
+- Requires Xcode 14+ for building
+
+### macOS
+
+- Minimum version: macOS 10.14
+- Requires code signing for distribution
+
+### Linux
+
+- Tested on Ubuntu 20.04+, Fedora 36+
+- Requires GTK 3.0
+
+### Windows
+
+- Minimum version: Windows 10
+- Uses Windows Media Foundation
+
+## 🐛 Troubleshooting
+
+### Connection Issues
+
+**Can't connect to server:**
+- Check server URL is correct
+- Ensure API is running (`docker-compose up`)
+- Check firewall settings
+- Try using IP address instead of localhost
+
+### Video Playback Issues
+
+**Videos won't play:**
+- Check internet connection
+- Verify video codec support
+- Try different video file
+- Check server streaming configuration
+
+**Buffering issues:**
+- Check network speed
+- Adjust video quality in settings
+- Check server performance
+
+### Build Issues
+
+**Flutter build fails:**
+```bash
+# Clean and rebuild
+flutter clean
+flutter pub get
+dart run build_runner build --delete-conflicting-outputs
+flutter run
+```
+
+**Platform-specific build issues:**
+- Android: Check SDK version, update Gradle
+- iOS: Update Xcode, check provisioning profiles
+- Desktop: Check platform dependencies installed
+
+## 📚 Resources
+
+- [Client GitHub Repository](https://github.com/DesterLib/desterlib-flutter)
+- [Flutter Documentation](https://flutter.dev/docs)
+- [Riverpod Documentation](https://riverpod.dev)
+- [media_kit Documentation](https://github.com/media-kit/media-kit)
+- [Effective Dart](https://dart.dev/guides/language/effective-dart)
+
+## 💬 Support
+
+- [GitHub Issues](https://github.com/DesterLib/desterlib-flutter/issues)
+- [GitHub Discussions](https://github.com/DesterLib/desterlib-flutter/discussions)
+- [Main DesterLib Discussions](https://github.com/DesterLib/desterlib/discussions)
+
diff --git a/apps/docs/src/content/docs/clients/overview.md b/apps/docs/src/content/docs/clients/overview.md
new file mode 100644
index 0000000..a05b194
--- /dev/null
+++ b/apps/docs/src/content/docs/clients/overview.md
@@ -0,0 +1,126 @@
+---
+title: Client Applications
+description: Overview of DesterLib client applications
+---
+
+The DesterLib client is a cross-platform application that connects to your DesterLib API Server, allowing you to browse and stream your media library across different platforms and devices.
+
+## What is the Client?
+
+The client provides:
+- **Media Browsing** - Explore your movies and TV shows
+- **Video Streaming** - Watch your content with smooth playback
+- **Watch Progress** - Automatic progress tracking across devices
+- **Search & Filter** - Find content quickly
+- **Multi-Platform** - Works on mobile, desktop, and TV (coming soon)
+
+**Repository**: [desterlib-flutter](https://github.com/DesterLib/desterlib-flutter)
+
+## Supported Platforms
+
+### 📱 Mobile
+- **Android** - Phones and tablets
+- **iOS** - iPhone and iPad
+
+### 💻 Desktop
+- **macOS** - Native desktop application
+- **Linux** - Native desktop application
+- **Windows** - Native desktop application
+
+### 📺 TV (In Development)
+- **Android TV** - TV interface with remote control
+- **Apple TV / tvOS** - Native TV experience
+
+**Repository**: [desterlib-flutter](https://github.com/DesterLib/desterlib-flutter)
+
+[Learn more about platform-specific setup →](/clients/flutter)
+
+## Features
+
+The Dester client provides a unified experience across all platforms:
+
+- **Media Library Browsing** - Browse movies and TV shows
+- **Video Streaming** - Smooth playback with adaptive quality
+- **Watch Progress** - Automatic tracking and resume
+- **Search & Filter** - Find content quickly
+- **Multi-Device Sync** - Progress syncs across devices
+- **Offline Viewing** - Download for offline playback (coming soon)
+- **System Integration** - Native look and feel on each platform
+- **Chromecast Support** - Cast to TV (coming soon)
+
+## API Compatibility
+
+The client communicates with the DesterLib API using REST API and WebSocket connections.
+
+### Version Compatibility
+
+| Platform | Min API Version | Recommended API Version |
+|----------|----------------|------------------------|
+| All Platforms | 0.1.0+ | Latest |
+
+:::caution
+Keep your client updated to match your API version for the best experience and latest features.
+:::
+
+## Development
+
+### Contributing
+
+See the [contributing guide](https://github.com/DesterLib/desterlib-flutter/blob/main/CONTRIBUTING.md) for client-specific development setup and workflows.
+
+:::tip
+The client follows the same [DesterLib contribution guidelines](/development/contributing) as all other projects:
+- Commit conventions
+- Version management
+- Code review process
+- Documentation standards
+:::
+
+### Platform-Specific Development
+
+Platform-specific setup and requirements:
+- **Android**: Android Studio, Android SDK 21+
+- **iOS**: Xcode 14+, iOS 12.0+
+- **macOS**: Xcode, macOS 10.14+
+- **Linux**: GTK 3.0, tested on Ubuntu 20.04+
+- **Windows**: Visual Studio 2019+, Windows 10+
+- **Android TV**: Android TV SDK (in development)
+- **Apple TV**: tvOS SDK (planned)
+
+### Building from Source
+
+Check out the [platform-specific setup guide](/clients/flutter) for detailed build instructions.
+
+## Platform Feature Status
+
+| Feature | Mobile | Desktop | TV |
+|---------|--------|---------|-----|
+| Browse Library | ✅ | ✅ | 🔜 |
+| Stream Videos | ✅ | ✅ | 🔜 |
+| Search | ✅ | ✅ | 🔜 |
+| Watch Progress | ✅ | ✅ | 🔜 |
+| Offline Downloads | 🔜 | 🔜 | ❌ |
+| Chromecast | 🔜 | 🔜 | N/A |
+| Picture-in-Picture | 🔜 | 🔜 | N/A |
+| System Integration | ✅ | ✅ | ✅ |
+| Remote Control | Touch | KB/Mouse | 🔜 |
+
+Legend: ✅ Available | 🔜 Planned | ❌ Not Available
+
+## Requesting Features
+
+Have an idea for a new feature or platform support?
+
+1. Check existing [feature requests](https://github.com/DesterLib/desterlib/discussions/categories/ideas)
+2. Search [client issues](https://github.com/DesterLib/desterlib-flutter/issues)
+3. Create a new discussion or issue
+4. Consider contributing! See our [contributing guide](/development/contributing)
+
+## Support
+
+Need help?
+
+- **General questions**: [GitHub Discussions](https://github.com/DesterLib/desterlib/discussions)
+- **Bug reports**: [Client Issues](https://github.com/DesterLib/desterlib-flutter/issues)
+- **Feature requests**: [Ideas Discussion](https://github.com/DesterLib/desterlib/discussions/categories/ideas)
+
diff --git a/apps/docs/src/content/docs/development/contributing.md b/apps/docs/src/content/docs/development/contributing.md
index b57e496..8cad4b8 100644
--- a/apps/docs/src/content/docs/development/contributing.md
+++ b/apps/docs/src/content/docs/development/contributing.md
@@ -1,10 +1,21 @@
 ---
 title: Contributing Guide
-description: How to contribute to DesterLib - for community members and external contributors
+description: How to contribute to DesterLib - applies to all projects
 ---
 
 Thank you for your interest in contributing to DesterLib! This guide will help you get started with contributing to the project.
 
+:::note[Applies to All Projects]
+This guide applies to **all DesterLib projects**:
+- **API Server** - Backend and API development
+- **Client Applications** - Mobile, desktop, and TV apps  
+- **Documentation** - This documentation site
+
+For project-specific setup:
+- [API Server Setup](/api/overview)
+- [Client Development](/clients/overview)
+:::
+
 ## 🎯 Quick Start
 
 New to DesterLib? Here's the fastest way to start contributing:
diff --git a/apps/docs/src/content/docs/development/versioning.md b/apps/docs/src/content/docs/development/versioning.md
index af252fc..2bbf0fc 100644
--- a/apps/docs/src/content/docs/development/versioning.md
+++ b/apps/docs/src/content/docs/development/versioning.md
@@ -1,18 +1,50 @@
 ---
 title: Versioning Guide
-description: How to track changes and manage releases with Changesets
+description: How to track changes and manage releases across all DesterLib projects
 ---
 
-This project uses [Changesets](https://github.com/changesets/changesets) for version management and changelog generation.
+DesterLib uses different versioning tools for different projects, but all follow semantic versioning and conventional commits.
 
-## Overview
+## Overview by Project
 
-We use **Changesets** to:
-- Track changes across our monorepo packages
+### API Server (Node.js/TypeScript)
+Uses **[Changesets](https://github.com/changesets/changesets)** to:
+- Track changes across monorepo packages
 - Generate changelogs automatically
 - Version packages based on changes
 - Simplify the release process
 
+### Client Applications (Flutter/Dart)
+Uses **conventional-changelog** to:
+- Generate changelogs from commit history
+- Automate version bumping in `pubspec.yaml`
+- Create releases with automated builds
+- Maintain semantic versioning
+
+---
+
+## Semantic Versioning
+
+All projects follow [Semantic Versioning 2.0.0](https://semver.org/):
+
+```
+MAJOR.MINOR.PATCH
+
+API Server:     1.2.3
+Client (Flutter): 1.2.3+4  (includes build number)
+```
+
+| Version | When to Bump | Example |
+|---------|-------------|---------|
+| **MAJOR** | Breaking changes | 0.9.0 → 1.0.0 |
+| **MINOR** | New features (backward-compatible) | 1.0.0 → 1.1.0 |
+| **PATCH** | Bug fixes | 1.1.0 → 1.1.1 |
+| **BUILD** | Flutter only - build number | 1.1.0+1 → 1.1.0+2 |
+
+---
+
+## API Server Versioning (Changesets)
+
 Each significant change should have an associated changeset file that describes what changed and the impact level (patch, minor, or major).
 
 ## Branching Strategy
@@ -307,7 +339,104 @@ git commit -m "chore: add changeset for breaking change"
 git push -u origin feat/api-v2-breaking
 ```
 
-## Commands Reference
+---
+
+## Client Versioning (Flutter)
+
+The Flutter client uses a simpler, automated workflow with `conventional-changelog`.
+
+### Quick Workflow
+
+```bash
+# 1. Work on feature branch
+git checkout -b feat/subtitle-support
+# ... make changes ...
+npm run commit  # Conventional commits
+
+# 2. Create PR, get it merged to main
+
+# 3. After merge, create release from main
+git checkout main
+git pull origin main
+npm run release  # Interactive script
+```
+
+### Release Script
+
+The `npm run release` command:
+1. ✅ Checks you're on `main` branch
+2. ✅ Shows current version
+3. ✅ Prompts for bump type (patch/minor/major/build)
+4. ✅ Updates `pubspec.yaml`
+5. ✅ Generates changelog from commits
+6. ✅ Creates release commit and tag
+7. ✅ Prompts you to push
+
+### Version Format
+
+```yaml
+version: 1.2.3+4
+#         │ │ │ │
+#         │ │ │ └─ Build number (auto-incremented)
+#         │ │ └─── PATCH
+#         │ └───── MINOR
+#         └─────── MAJOR
+```
+
+### Automated Builds
+
+When you push a tag, GitHub Actions automatically:
+- Creates GitHub Release with changelog
+- Builds for all platforms (Android, iOS, macOS, Linux, Windows)
+- Attaches builds to the release
+
+### Example: Feature Release
+
+```bash
+# After PRs are merged to main
+git checkout main
+git pull origin main
+
+# Run release script
+npm run release
+
+# Interactive prompts:
+# Current version: 0.1.5+3
+# Select version bump type:
+#   1) Patch (bug fixes)         - 0.1.5 → 0.1.6+1
+#   2) Minor (new features)      - 0.1.5 → 0.2.0+1
+#   3) Major (breaking changes)  - 0.1.5 → 1.0.0+1
+# 
+# Enter choice: 2
+
+# Changelog is generated from commits:
+# ## [0.2.0] - 2024-10-27
+# 
+# ### Features
+# * **player:** add subtitle support
+# * **ui:** add dark mode theme
+# 
+# ### Bug Fixes
+# * **auth:** resolve token refresh
+
+# Confirm and push
+git push origin main --tags
+
+# Check: https://github.com/DesterLib/desterlib-flutter/releases
+```
+
+### Client Commands Reference
+
+| Command | Description |
+|---------|-------------|
+| `npm run commit` | Create conventional commit |
+| `npm run release` | Interactive release (must be on main) |
+| `npm run version:bump patch` | Manual version bump |
+| `npm run changelog:generate` | Generate changelog only |
+
+---
+
+## API Commands Reference
 
 | Command | Description |
 |---------|-------------|

From 880bd1031b7ab65de25afd66087c40b43a8dc644 Mon Sep 17 00:00:00 2001
From: AlkenD <desteralken@gmail.com>
Date: Tue, 28 Oct 2025 01:06:46 +0530
Subject: [PATCH 2/2] docs: add GitHub Pages deployment workflow for Astro docs

- Configure GitHub Actions workflow for automatic deployment
- Use Turborepo with pnpm for efficient builds
- Deploy on pushes to main branch affecting docs
- Support manual workflow dispatch
---
 .github/workflows/deploy-docs.yml | 25 ++++++++++++++-----------
 1 file changed, 14 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
index 848a8bf..7853971 100644
--- a/.github/workflows/deploy-docs.yml
+++ b/.github/workflows/deploy-docs.yml
@@ -1,18 +1,24 @@
-name: Deploy Documentation
+name: Deploy Docs to GitHub Pages
 
 on:
+  # Runs on pushes targeting the default branch
   push:
-    branches: [main]
+    branches: ["main"]
     paths:
       - 'apps/docs/**'
       - '.github/workflows/deploy-docs.yml'
+
+  # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
 permissions:
   contents: read
   pages: write
   id-token: write
 
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
 concurrency:
   group: "pages"
   cancel-in-progress: false
@@ -27,13 +33,13 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 9
+          version: 9.0.0
 
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
-          cache: 'pnpm'
+          node-version: "18"
+          cache: "pnpm"
 
       - name: Setup Pages
         uses: actions/configure-pages@v4
@@ -41,15 +47,13 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
-      - name: Build docs
-        run: |
-          cd apps/docs
-          pnpm build
+      - name: Build with Turbo
+        run: pnpm turbo build --filter=docs
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: apps/docs/dist
+          path: ./apps/docs/dist
 
   deploy:
     environment:
@@ -61,4 +65,3 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
-