docs: normalize list indentation and fix formatting

Adjust documentation lists and code blocks for consistent
indentation and spacing across CLAUDE.md. Convert mixed dash
and nested list levels to use uniform two-space indentation for
subitems, reflow a few wrapped lines, and add blank lines where
needed to separate sections and examples. These changes improve
readability and maintain a consistent markdown structure for the
project documentation.
This commit is contained in:
4gray committed 2025-11-23 18:50:46 +01:00
1 parent 7da2202119
commit 13c05c85b0
4 files changed
+100 -46

No files matched your search

+5 -1
View File
@@ -9,5 +9,9 @@
], ],
"deny": [], "deny": [],
"ask": [] "ask": []
} },
"enabledMcpjsonServers": [
"nx-mcp"
],
"enableAllProjectMcpServers": true
} }
+9
View File
@@ -0,0 +1,9 @@
{
"mcpServers": {
"nx-mcp": {
"type": "stdio",
"command": "npx",
"args": ["nx", "mcp"]
}
}
}
+3
View File
@@ -0,0 +1,3 @@
{
"recommendations": ["ms-playwright.playwright", "esbenp.prettier-vscode"]
}
+83 -45
View File
@@ -94,23 +94,25 @@ This is an Nx monorepo with the following structure:
- **apps/electron-backend** - Electron main process - **apps/electron-backend** - Electron main process
- **apps/web-e2e** - Playwright end-to-end tests - **apps/web-e2e** - Playwright end-to-end tests
- **libs/** - Shared libraries: - **libs/** - Shared libraries:
- **m3u-state** - NgRx state management for playlists - **m3u-state** - NgRx state management for playlists
- **services** - Abstract DataService and implementations - **services** - Abstract DataService and implementations
- **shared/interfaces** - TypeScript interfaces and types - **shared/interfaces** - TypeScript interfaces and types
- **shared/m3u-utils** - M3U playlist utilities - **shared/m3u-utils** - M3U playlist utilities
- **ui/components** - Reusable UI components - **ui/components** - Reusable UI components
- **ui/pipes** - Angular pipes - **ui/pipes** - Angular pipes
- **ui/shared-portals** - Portal-related UI components - **ui/shared-portals** - Portal-related UI components
### Frontend Architecture (Angular) ### Frontend Architecture (Angular)
**State Management**: Uses NgRx for playlist state management: **State Management**: Uses NgRx for playlist state management:
- Store configuration in `apps/web/src/app/app.config.ts` - Store configuration in `apps/web/src/app/app.config.ts`
- Playlist state, actions, effects, and reducers in `libs/m3u-state/` - Playlist state, actions, effects, and reducers in `libs/m3u-state/`
- Entity adapter pattern for managing playlists collection - Entity adapter pattern for managing playlists collection
- Router store integration for route-based state - Router store integration for route-based state
**Routing**: Lazy-loaded routes in `apps/web/src/app/app.routes.ts` **Routing**: Lazy-loaded routes in `apps/web/src/app/app.routes.ts`
- Home/playlists overview: `/` - Home/playlists overview: `/`
- Video player: `/playlists/:id` or `/iptv` - Video player: `/playlists/:id` or `/iptv`
- Xtream Codes: `/xtreams/:id` (different routes for Electron vs web) - Xtream Codes: `/xtreams/:id` (different routes for Electron vs web)
@@ -118,85 +120,96 @@ This is an Nx monorepo with the following structure:
- Settings: `/settings` - Settings: `/settings`
**Service Architecture** (Factory Pattern): **Service Architecture** (Factory Pattern):
- Abstract `DataService` class in `libs/services/src/lib/data.service.ts` defines the contract - Abstract `DataService` class in `libs/services/src/lib/data.service.ts` defines the contract
- Two environment-specific implementations: - Two environment-specific implementations:
- `ElectronService` (`apps/web/src/app/services/electron.service.ts`) - Uses IPC to communicate with Electron backend - `ElectronService` (`apps/web/src/app/services/electron.service.ts`) - Uses IPC to communicate with Electron backend
- `PwaService` (`apps/web/src/app/services/pwa.service.ts`) - Uses HTTP API and IndexedDB for standalone web version - `PwaService` (`apps/web/src/app/services/pwa.service.ts`) - Uses HTTP API and IndexedDB for standalone web version
- Factory function `DataFactory()` in `apps/web/src/app/app.config.ts` determines which implementation to inject: - Factory function `DataFactory()` in `apps/web/src/app/app.config.ts` determines which implementation to inject:
```typescript ```typescript
if (window.electron) { if (window.electron) {
return new ElectronService(); return new ElectronService();
} }
return new PwaService(); return new PwaService();
``` ```
**Data Storage (Environment-Specific)**: **Data Storage (Environment-Specific)**:
- **Electron**: libSQL/SQLite database via Drizzle ORM - **Electron**: libSQL/SQLite database via Drizzle ORM
- Location: `~/.iptvnator/databases/iptvnator.db` - Location: `~/.iptvnator/databases/iptvnator.db`
- Full-featured relational database with foreign keys and indexes - Full-featured relational database with foreign keys and indexes
- Supports local file or remote Turso instance via env vars - Supports local file or remote Turso instance via env vars
- **PWA (Web)**: IndexedDB via `ngx-indexed-db` - **PWA (Web)**: IndexedDB via `ngx-indexed-db`
- Browser-based NoSQL storage - Browser-based NoSQL storage
- Same schema structure but implemented in IndexedDB - Same schema structure but implemented in IndexedDB
- Limited by browser storage quotas - Limited by browser storage quotas
### Backend Architecture (Electron) ### Backend Architecture (Electron)
**Main Entry**: `apps/electron-backend/src/main.ts` **Main Entry**: `apps/electron-backend/src/main.ts`
- Bootstraps Electron app and initializes database - Bootstraps Electron app and initializes database
- Registers event handlers for IPC communication - Registers event handlers for IPC communication
**Database**: **Database**:
- **ORM**: Drizzle ORM with libSQL (local SQLite file or remote Turso) - **ORM**: Drizzle ORM with libSQL (local SQLite file or remote Turso)
- **Location**: `~/.iptvnator/databases/iptvnator.db` (avoids spaces in path) - **Location**: `~/.iptvnator/databases/iptvnator.db` (avoids spaces in path)
- **Schema** (`apps/electron-backend/src/app/database/schema.ts`): - **Schema** (`apps/electron-backend/src/app/database/schema.ts`):
- `playlists` - Playlist metadata (M3U, Xtream, Stalker) - `playlists` - Playlist metadata (M3U, Xtream, Stalker)
- `categories` - Content categories (live, movies, series) - `categories` - Content categories (live, movies, series)
- `content` - Streams/VOD/series items - `content` - Streams/VOD/series items
- `favorites` - User favorites - `favorites` - User favorites
- `recentlyViewed` - Watch history - `recentlyViewed` - Watch history
- **Connection**: `apps/electron-backend/src/app/database/connection.ts` - **Connection**: `apps/electron-backend/src/app/database/connection.ts`
- Auto-creates tables on init - Auto-creates tables on init
- Supports local file or remote via env vars (`LIBSQL_URL`, `LIBSQL_AUTH_TOKEN`) - Supports local file or remote via env vars (`LIBSQL_URL`, `LIBSQL_AUTH_TOKEN`)
**IPC Communication**: **IPC Communication**:
- **Preload script**: `apps/electron-backend/src/app/api/main.preload.ts` - **Preload script**: `apps/electron-backend/src/app/api/main.preload.ts`
- Exposes `window.electron` API via `contextBridge` - Exposes `window.electron` API via `contextBridge`
- All IPC channels defined here (playlist operations, EPG, database CRUD, external players, etc.) - All IPC channels defined here (playlist operations, EPG, database CRUD, external players, etc.)
- **Event handlers**: `apps/electron-backend/src/app/events/` - **Event handlers**: `apps/electron-backend/src/app/events/`
- `database.events.ts` - Database CRUD operations - `database.events.ts` - Database CRUD operations
- `playlist.events.ts` - Playlist import/update - `playlist.events.ts` - Playlist import/update
- `epg.events.ts` - EPG fetch and parsing (uses worker) - `epg.events.ts` - EPG fetch and parsing (uses worker)
- `xtream.events.ts` - Xtream Codes API - `xtream.events.ts` - Xtream Codes API
- `stalker.events.ts` - Stalker portal API - `stalker.events.ts` - Stalker portal API
- `player.events.ts` - External player (MPV, VLC) integration - `player.events.ts` - External player (MPV, VLC) integration
- `settings.events.ts` - App settings - `settings.events.ts` - App settings
- `electron.events.ts` - App version, etc. - `electron.events.ts` - App version, etc.
**Workers**: **Workers**:
- EPG parsing runs in worker thread: `apps/electron-backend/src/app/workers/epg-parser.worker.ts` - EPG parsing runs in worker thread: `apps/electron-backend/src/app/workers/epg-parser.worker.ts`
### Key Features ### Key Features
**Playlist Support**: **Playlist Support**:
- M3U/M3U8 files (local or URL) - M3U/M3U8 files (local or URL)
- Xtream Codes API (`username`, `password`, `serverUrl`) - Xtream Codes API (`username`, `password`, `serverUrl`)
- Stalker portal (`macAddress`, `url`) - Stalker portal (`macAddress`, `url`)
**Video Players**: **Video Players**:
- Built-in HTML5 player with HLS.js or Video.js - Built-in HTML5 player with HLS.js or Video.js
- External players: MPV, VLC (via IPC to Electron backend) - External players: MPV, VLC (via IPC to Electron backend)
**EPG (Electronic Program Guide)**: **EPG (Electronic Program Guide)**:
- XMLTV format support - XMLTV format support
- Background parsing in worker thread - Background parsing in worker thread
- Stored in database for quick lookup - Stored in database for quick lookup
**Favorites and Recently Viewed**: **Favorites and Recently Viewed**:
- Per-playlist favorites and global favorites - Per-playlist favorites and global favorites
- Recently viewed tracks watch history - Recently viewed tracks watch history
**Internationalization**: **Internationalization**:
- Uses `@ngx-translate` with 16 language files in `apps/web/src/assets/i18n/` - Uses `@ngx-translate` with 16 language files in `apps/web/src/assets/i18n/`
## Development Notes ## Development Notes
@@ -204,34 +217,39 @@ This is an Nx monorepo with the following structure:
### Environment Detection and Dual-Mode Architecture ### Environment Detection and Dual-Mode Architecture
The app determines whether it's running in Electron or as a PWA by checking: The app determines whether it's running in Electron or as a PWA by checking:
```typescript ```typescript
window.electron // truthy in Electron, undefined in browser window.electron; // truthy in Electron, undefined in browser
``` ```
**Why Dual Mode?** **Why Dual Mode?**
IPTVnator supports both Electron (desktop app) and PWA (web browser) to provide flexibility: IPTVnator supports both Electron (desktop app) and PWA (web browser) to provide flexibility:
- **Electron**: Full-featured desktop experience with local database, external player support (MPV/VLC), and native file system access - **Electron**: Full-featured desktop experience with local database, external player support (MPV/VLC), and native file system access
- **PWA**: Lightweight web version that runs in any browser without installation - **PWA**: Lightweight web version that runs in any browser without installation
**Environment-Specific Behavior**: **Environment-Specific Behavior**:
- `app.config.ts` - `DataFactory()` selects DataService implementation based on environment - `app.config.ts` - `DataFactory()` selects DataService implementation based on environment
- `app.routes.ts` - Different routes for Xtream portals (Electron uses Tauri-based routes, PWA uses standard routes) - `app.routes.ts` - Different routes for Xtream portals (Electron uses Tauri-based routes, PWA uses standard routes)
- Storage layer switches automatically: - Storage layer switches automatically:
- Electron → libSQL/Drizzle ORM → `~/.iptvnator/databases/iptvnator.db` - Electron → libSQL/Drizzle ORM → `~/.iptvnator/databases/iptvnator.db`
- PWA → IndexedDB → Browser storage - PWA → IndexedDB → Browser storage
- External player support (MPV/VLC) only available in Electron - External player support (MPV/VLC) only available in Electron
- File system operations only available in Electron (uploading playlists from disk) - File system operations only available in Electron (uploading playlists from disk)
**Base Href Configuration**: **Base Href Configuration**:
The app uses different base href values depending on the build target: The app uses different base href values depending on the build target:
- **Development & PWA**: `baseHref="/"` (from `index.html`) - **Development & PWA**: `baseHref="/"` (from `index.html`)
- Used by: `npm run serve:frontend`, `npm run build:frontend:pwa` - Used by: `npm run serve:frontend`, `npm run build:frontend:pwa`
- For web servers with proper routing - For web servers with proper routing
- **Electron Production**: `baseHref="./"` (overridden in build config) - **Electron Production**: `baseHref="./"` (overridden in build config)
- Used by: `npm run build:backend`, `npm run make:app` - Used by: `npm run build:backend`, `npm run make:app`
- Required for `file://` protocol in Electron - Required for `file://` protocol in Electron
Build configurations in `apps/web/project.json`: Build configurations in `apps/web/project.json`:
- `production`: Electron build with `baseHref="./"` - `production`: Electron build with `baseHref="./"`
- `pwa`: Web deployment with `baseHref="/"` - `pwa`: Web deployment with `baseHref="/"`
- `development`: Dev mode with `baseHref="/"` from index.html - `development`: Dev mode with `baseHref="/"` from index.html
@@ -248,6 +266,7 @@ The factory pattern ensures a single codebase works in both environments without
### Nx Commands ### Nx Commands
Use `nx` CLI for better performance: Use `nx` CLI for better performance:
```bash ```bash
nx run <project>:<target> nx run <project>:<target>
# Example: nx run web:build # Example: nx run web:build
@@ -255,6 +274,7 @@ nx run <project>:<target>
``` ```
To run multiple projects: To run multiple projects:
```bash ```bash
nx run-many --target=test --all nx run-many --target=test --all
``` ```
@@ -262,6 +282,7 @@ nx run-many --target=test --all
### Electron Build Process ### Electron Build Process
The Electron backend depends on the web app being built first: The Electron backend depends on the web app being built first:
- `electron-backend:build` depends on `web:build` - `electron-backend:build` depends on `web:build`
- Output goes to `dist/apps/electron-backend` (backend) and `dist/apps/web` (frontend) - Output goes to `dist/apps/electron-backend` (backend) and `dist/apps/web` (frontend)
- Packaging combines both into distributable - Packaging combines both into distributable
@@ -273,18 +294,35 @@ No formal migration system yet. Schema changes are applied via raw SQL in `conne
### Common Patterns ### Common Patterns
**IPC Communication**: **IPC Communication**:
1. Define handler in appropriate events file (e.g., `database.events.ts`) 1. Define handler in appropriate events file (e.g., `database.events.ts`)
2. Register with `ipcMain.handle()` in the event bootstrap function 2. Register with `ipcMain.handle()` in the event bootstrap function
3. Expose in preload script via `contextBridge.exposeInMainWorld()` 3. Expose in preload script via `contextBridge.exposeInMainWorld()`
4. Call from Angular via `window.electron.<methodName>()` 4. Call from Angular via `window.electron.<methodName>()`
**Adding New Playlist Source**: **Adding New Playlist Source**:
1. Add type to `libs/shared/interfaces/src/lib/playlist.interface.ts` 1. Add type to `libs/shared/interfaces/src/lib/playlist.interface.ts`
2. Create event handler in `apps/electron-backend/src/app/events/` 2. Create event handler in `apps/electron-backend/src/app/events/`
3. Add UI in `apps/web/src/app/home/` 3. Add UI in `apps/web/src/app/home/`
4. Update database schema if needed 4. Update database schema if needed
**State Management**: **State Management**:
- Use NgRx for global application state (playlists) - Use NgRx for global application state (playlists)
- Use component stores (`@ngrx/component-store`) for feature-specific state - Use component stores (`@ngrx/component-store`) for feature-specific state
- Use NgRx signals for reactive data streams - Use NgRx signals for reactive data streams
<!-- nx configuration start-->
<!-- Leave the start & end comments to automatically receive updates. -->
# General Guidelines for working with Nx
- When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through `nx` (i.e. `nx run`, `nx run-many`, `nx affected`) instead of using the underlying tooling directly
- You have access to the Nx MCP server and its tools, use them to help the user
- When answering questions about the repository, use the `nx_workspace` tool first to gain an understanding of the workspace architecture where applicable.
- When working in individual projects, use the `nx_project_details` mcp tool to analyze and understand the specific project structure and dependencies
- For questions around nx configuration, best practices or if you're unsure, use the `nx_docs` tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
- If the user needs help with an Nx configuration or project graph error, use the `nx_workspace` tool to get any errors
<!-- nx configuration end-->