NeveWatch Global Architecture

NeveWatch is an open-source white-label IPTV streaming platform. The repository contains the control plane, storefront/admin web app, client playback apps, CI/CD infrastructure, security automation, monitoring, backups, and automated streaming-node deployment.

This document is the top-level map for new contributors and operators. Use it to understand how the full system fits together before reading the deeper setup guides in documentation/ and docs/.

Product Goal

NeveWatch is designed to let an operator launch branded IPTV stores quickly:

• Create and manage stores, users, screens, profiles, IPTV providers, streams, categories, subscriptions, wallets, affiliates, and landing pages.
• Accept subscription payments through Stripe and PayPal.
• Serve web, mobile, and TV-oriented client applications from the same backend.
• Deploy central application servers with Jenkins and Ansible.
• Add private or global streaming edge servers automatically, so stream bandwidth can move away from the central API server.
• Keep the deployment secure, observable, and recoverable with API keys, isolated Docker networks, backups, monitoring, and health checks.

Repository Map

Path	Purpose
nevewatch_backend/	NestJS API, multi-tenant business logic, payments, subscriptions, IPTV, streaming routing, WebSockets, queues, and admin APIs.
nevewatch_web_app/	Angular web application for admin, store owner, user, landing-builder, IPTV viewer, affiliate, and mobile-app-builder workflows.
nevewatch_mobile/	Flutter client app for users, playback, subscriptions, account screens, localization, and app update flows.
nevewatch_webos/	Angular/webOS and TV-style build target, including webOS packaging and Electron-related tooling.
streaming-node/	Go streaming edge node that validates stream tokens, proxies IPTV traffic, reports heartbeat/load, and can optionally integrate WebRTC/SRS.
ansible/	Server provisioning and deployment automation for app servers, monitoring, backups, and streaming nodes.
jenkins-pipelines/	Jenkins pipeline variants for setup, deployment, updates, health checks, monitoring, and node deployment.
nevewatch-ci/	Jenkins and private registry container setup, nginx configs, and CI support files.
security/	Security policies and helpers, including AppArmor, SELinux, Docker authorization policy, and API key tooling.
security-service/	NestJS service for API key/security validation workflows.
monitoring/	Prometheus, Grafana, Alertmanager, Elasticsearch, Kibana, and Filebeat configuration.
documentation/	Step-by-step infrastructure setup guides for the central host, registry, Jenkins, credentials, and client servers.
docs/	Streaming-node onboarding/deployment guides, Postman collections, and design notes.
backup_db/	Database dump seed/backup artifacts used during server bootstrap or restoration. Treat contents as sensitive in public distributions.

System Context

Users / admins / store owners
        |
        v
Angular web app / Flutter mobile / webOS app
        |
        v
Nginx reverse proxy with TLS
        |
        v
NestJS backend API
        |
        +--> MongoDB: tenants, stores, users, subscriptions, streams, payments
        +--> Redis: cache, queue, throttling, async processing
        +--> Stripe and PayPal: checkout, webhooks, refunds, recurring payments
        +--> Jenkins: automated streaming-node deployment
        +--> WebSockets: chat, notifications, build/provisioning status
        |
        v
Streaming route selection
        |
        +--> Streaming edge node: direct stream proxy and heartbeat
        +--> Fallback: central backend stream proxy when no node is healthy

The backend is the control plane. It should not carry all video bandwidth in a scaled production deployment. Streaming nodes are the data plane and serve users directly after the backend issues a short-lived route token.

Runtime Components

Backend API

The backend lives in nevewatch_backend/ and is built with NestJS, MongoDB, Redis, Mongoose, Bull queues, JWT auth, throttling, WebSockets, Stripe, PayPal, and Swagger.

Main responsibilities:

• Authentication, JWT, profiles, users, roles, and permissions.
• Multi-tenant store management.
• IPTV providers, IPTV accounts, streams, categories, favorites, continue-watching, and route selection.
• Store subscriptions, user subscriptions, coupons, wallets, payments, and refunds.
• Stripe and PayPal checkout/webhook flows.
• Affiliate programs, links, commissions, payouts, and analytics.
• Landing page templates and custom domain management.
• Mobile app builder and store application build tracking.
• Streaming node registration, deployment, callbacks, heartbeat, and node selection.
• Audit logs, health checks, logging, cache, and queue processing.

Important files:

• nevewatch_backend/src/app.module.ts wires the main modules.
• nevewatch_backend/src/config/configuration.ts maps environment variables.
• nevewatch_backend/src/config/validation.schema.ts validates runtime configuration.
• nevewatch_backend/src/modules/streaming-nodes/ manages node registration, deployment, heartbeat, and status.
• nevewatch_backend/src/modules/store-subscriptions/ and nevewatch_backend/src/modules/payments/ handle payment/subscription flows.

Web App

The web app lives in nevewatch_web_app/ and is built with Angular 18.

Main surfaces:

• Admin dashboard and platform metrics.
• Store management: stores, users, screens, IPTV accounts, providers, streams, categories, subscription plans, wallets, and payments.
• Client login/register and user subscription management.
• IPTV viewer and playback UI.
• Landing page builder and CMS-like page rendering.
• Affiliate portal and affiliate admin screens.
• Mobile app builder UI.

Important files:

• nevewatch_web_app/package.json
• nevewatch_web_app/src/environments/
• nevewatch_web_app/src/assets/runtime-env.template.js
• nevewatch_web_app/src/app/

Mobile App

The mobile app lives in nevewatch_mobile/ and is built with Flutter.

Main areas:

• Auth, onboarding, user account, subscriptions, plans, screens, home, favorites, continue-watching, playback, localization, app updates, and crash reporting.
• Feature-oriented clean architecture folders: application, domain, infrastructure, presentation, and shared.

Important files:

• nevewatch_mobile/pubspec.yaml
• nevewatch_mobile/lib/core/
• nevewatch_mobile/lib/home/
• nevewatch_mobile/lib/subscription/
• nevewatch_mobile/lib/screen/

TV / webOS App

The webOS target lives in nevewatch_webos/. It shares Angular patterns with the web app but includes platform packaging files, webOS metadata, and build scripts.

Important files:

• nevewatch_webos/WEBOS_GUIDE.md
• nevewatch_webos/build-webos.sh
• nevewatch_webos/webos_meta/
• nevewatch_webos/output/

Streaming Node

The streaming node lives in streaming-node/ and is written in Go.

Responsibilities:

• Verify short-lived JWT stream tokens locally.
• Confirm the token was issued for this node.
• Proxy IPTV stream traffic directly to the client.
• Report heartbeat, CPU, and active stream count to the backend.
• Optionally run with SRS/WebRTC configuration when enabled.

Important files:

• streaming-node/main.go
• streaming-node/config/config.go
• streaming-node/handlers/
• streaming-node/heartbeat/
• streaming-node/registry/
• streaming-node/webrtc/
• streaming-node/Dockerfile
• streaming-node/docker-compose.yml
• streaming-node/systemd/streaming-node.service

Deployment Architecture

Central Server

The central application server runs the platform control plane:

Public internet
      |
      v
Nginx + TLS
      |
      +--> frontend container on localhost:4000
      +--> backend container on localhost:3000
              |
              +--> mongodb container on private Docker network
              +--> redis container on private Docker network

The main compose file is docker-compose.yml. It defines:

• mongodb with local-only host binding and persistent bind-mounted data.
• redis with local-only host binding and append-only persistence.
• backend from the private registry, read-only root filesystem, non-root user, dropped capabilities, API key validation, and localhost-only port exposure.
• frontend from the private registry, localhost-only port exposure, and runtime env injection.
• nevewatch-secure Docker network.

The generated server-side compose templates live in ansible/templates/docker/docker-compose.yml.j2.

CI Server

The CI server runs:

• Jenkins for build, test, image push, deployment, health checks, backups, and streaming-node deployment.
• A private Docker registry for backend/frontend/streaming-node images.
• Nginx and Let's Encrypt certificates for jenkins.<domain> and registry.<domain>.

Start with:

• documentation/README.md
• documentation/steps/step-1-central-host-setup.md
• documentation/steps/step-2-registry-jenkins.md
• documentation/steps/step-3-jenkins-credentials-ssh.md

Application Server Deployment Flow

Developer pushes code
        |
        v
Jenkins pipeline
        |
        +--> checkout repository
        +--> build backend and frontend Docker images
        +--> push images to private registry
        +--> run Ansible against target inventory
        +--> install or verify prerequisites
        +--> write env files and docker-compose.yml
        +--> configure nginx, firewall, SSL, backup scripts, monitoring agents
        +--> pull images and restart services
        +--> run health checks

Main files:

• Jenkinsfile
• jenkins-pipelines/Jenkinsfile
• jenkins-pipelines/Jenkinsfile.simple
• jenkins-pipelines/Jenkinsfile.nodes
• ansible/playbooks/environment-deploy.yml
• ansible/playbooks/health-check.yml
• ansible/inventories/staging/hosts.yml
• ansible/inventories/production/hosts.yml

Adding a New Client Server

For a new white-label/customer server:

1. Create the deploy user on the target server.
2. Add the Jenkins SSH public key.
3. Add the server to the correct Ansible inventory.
4. Generate and install server API keys.
5. Configure Docker registry access.
6. Restore or seed MongoDB data if needed.
7. Run the Jenkins deployment pipeline.
8. Verify nginx, TLS, backend, frontend, MongoDB, Redis, and health endpoints.

Detailed runbook: documentation/steps/step-4-new-client-server.md.

Automated Streaming Node Architecture

Streaming nodes can be global or private:

• Global nodes are shared by all stores.
• Private nodes belong to one store and are preferred during routing.

Runtime request flow:

Client app
    |
    v
GET /streaming/node-route?streamId=...&streamType=...
    |
    v
NestJS selects healthy node by store, status, heartbeat age, and load
    |
    v
Backend returns { nodeUrl, token, expiresIn }
    |
    v
Client connects directly to streaming node
    |
    v
Node validates token and proxies IPTV stream

Automated deployment flow:

Store/admin requests node deployment
        |
        v
POST /v1/streaming-nodes/stores/:id/deploy
        |
        v
NestJS pre-registers node as provisioning
        |
        v
Jenkins deploy-streaming-node job
        |
        +--> build streaming-node Docker image
        +--> push image to private registry
        +--> run Ansible playbook on target server
        +--> install Docker
        +--> write /opt/streaming-node/.env
        +--> start container on port 3008
        +--> run health check
        |
        v
Jenkins callback updates backend status
        |
        v
Streaming node heartbeat marks node active

Important files:

• docs/streaming-node-deployment-guide.md
• docs/streaming-node-onboarding.md
• documentation/steps/step-5-streaming-node-deployment-guide.md
• devops/streaming-node/Jenkinsfile
• ansible/playbooks/deploy-streaming-node.yml
• ansible/templates/streaming-node/docker-compose.yml.j2
• ansible/templates/streaming-node/streaming-node.env.j2
• ansible/scripts/streaming-node/setup-jenkins-server.sh
• ansible/scripts/streaming-node/setup-streaming-server.sh

Required backend env values:

JENKINS_URL=https://jenkins.<domain>
JENKINS_USER=admin
JENKINS_API_TOKEN=<jenkins-api-token>
JENKINS_JOB_NAME=deploy-streaming-node
JENKINS_CALLBACK_SECRET=<long-random-secret>
PUBLIC_API_URL=https://api.<domain>

Required node env values:

BACKEND_URL=https://api.<domain>
NODE_ID=<backend-node-id>
NODE_SECRET=<one-time-node-secret>
JWT_SECRET=<same-value-as-backend-JWT_SECRET>

Payments and Subscriptions

Payment logic is handled in the backend and surfaced in the web/mobile apps.

Supported providers:

• Stripe
• PayPal

Main flows:

• Store subscription checkout.
• User IPTV subscription checkout.
• Webhook confirmation.
• Auto-renewal and expiry processing.
• Refund/cancellation decisions.
• Payment history and email notifications.

Important backend areas:

• nevewatch_backend/src/modules/store-subscriptions/
• nevewatch_backend/src/modules/users-subscriptions/
• nevewatch_backend/src/modules/payments/
• nevewatch_backend/src/modules/subscription-process/
• nevewatch_backend/src/config/configuration.ts

Important env values:

STRIPE_API_SECRET_KEY=
STRIPE_SECRET_KEY=
STRIPE_PUBLISHABLE_KEY=
STRIPE_WEBHOOK_SECRET=

PAYPAL_CLIENT_ID=
PAYPAL_CLIENT_SECRET=
PAYPAL_WEBHOOK_ID=
PAYPAL_ENVIRONMENT=sandbox

Webhook routes are intentionally excluded from API-key middleware in nevewatch_backend/src/common/middleware/api-key.middleware.ts; they must be protected by provider webhook signature validation instead.

Security Model

Security is layered across infrastructure, containers, API access, and app logic.

Infrastructure:

• Nginx terminates TLS.
• Only public HTTP/HTTPS and SSH should be reachable from the internet.
• MongoDB and Redis are bound to localhost or private Docker networks.
• Jenkins deploys through SSH as a dedicated deploy user.
• Registry access uses Jenkins credentials, not hardcoded secrets.

Containers:

• Containers drop Linux capabilities where possible.
• Backend uses read-only root filesystem and non-root user.
• Temporary writable paths are mounted as tmpfs.
• Docker logs are size-limited.
• Persistent volumes are bind-mounted under /opt/nevewatch-<env>/data.

Application:

• JWT authenticates users.
• API keys protect backend/frontend/server-to-server flows when enabled.
• Tenant context and store permissions isolate stores.
• Throttling limits abuse.
• Audit logs track sensitive operations.
• Streaming nodes validate short-lived stream tokens without calling the backend on every request.

Security-related files:

• security/
• security-service/
• security-validator.sh
• nevewatch_backend/security-validator.sh
• nevewatch_backend/src/common/middleware/api-key.middleware.ts
• ansible/roles/api_key_generation/
• docker-compose.yml

Minimum production requirements:

• Replace all default secrets before deployment.
• Use strong JWT_SECRET, ENCRYPTION_KEY, Redis password, MongoDB credentials, Jenkins password, registry password, and JENKINS_CALLBACK_SECRET.
• Do not publish real database dumps, credentials, private keys, .env files, or customer IPTV account data.
• Keep webhook secrets provider-specific and rotate them if leaked.
• Keep Jenkins and the private registry behind TLS and strong credentials.

Backup and Recovery

Backups are managed through Ansible and generated server scripts.

Main files:

• ansible/playbooks/backup.yml
• ansible/templates/scripts/backup-db.sh.j2
• ansible/templates/scripts/restor-db.sh.j2
• backup_db/

Backup flow:

Jenkins or operator triggers backup.yml
        |
        v
Ansible runs /opt/nevewatch-<env>/backup-db.sh
        |
        v
mongodump runs inside or against the MongoDB container
        |
        v
backup written to /opt/nevewatch-<env>/automated-backups
        |
        v
old backups deleted after configured retention

Recommended policy:

• Run automated daily backups for production.
• Keep at least 7 days for staging and 30 days for production.
• Store a copy off-server, not only on the same VPS.
• Test restore on a staging server before relying on backups.
• Never commit production backups into the public repository.

Monitoring and Health

Monitoring is defined in docker-compose.monitoring.yml and monitoring/.

Components:

• Prometheus for metrics.
• Grafana for dashboards.
• Alertmanager for alerts.
• Node Exporter for server metrics.
• cAdvisor for container metrics.
• Elasticsearch, Kibana, and Filebeat for log collection.

Deployment and operations:

• ansible/playbooks/environment-deploy.yml can enable lightweight monitoring agents.
• ansible/playbooks/update-grafana-dashboards.yml updates dashboard provisioning.
• jenkins-pipelines/Jenkinsfile.monitoring and nevewatch-ci/pipelines/grafana-dashboards/Jenkinsfile support monitoring pipelines.
• ansible/playbooks/health-check.yml validates server health after deploy.

Environment and Secret Ownership

Environment files are generated by Ansible templates:

• ansible/templates/env/.env.j2
• ansible/templates/env/.env.backend.j2
• ansible/templates/env/.env.frontend.j2

On a server, expected deployment paths are:

/opt/nevewatch-<environment>/
    .env
    .env.backend.<environment>
    .env.frontend.<environment>
    docker-compose.yml
    backup-db.sh
    restor-db.sh
    data/
    logs/
    uploads/
    automated-backups/

Secrets should come from Jenkins credentials, Ansible inventory/group variables, or a secret manager. Do not hardcode new secrets in source files.

First-Time Setup Path

For a new operator:

1. Fork the repository.
2. Replace registry hostnames, Git repository URLs, domains, and inventory values.
3. Prepare the CI host with documentation/steps/step-1-central-host-setup.md.
4. Start the private registry and Jenkins with documentation/steps/step-2-registry-jenkins.md.
5. Add Jenkins credentials and SSH keys with documentation/steps/step-3-jenkins-credentials-ssh.md.
6. Add the first app server with documentation/steps/step-4-new-client-server.md.
7. Run the main Jenkins deployment pipeline.
8. Verify health checks, SSL, frontend, backend, database, Redis, and monitoring.
9. Configure Stripe/PayPal sandbox keys and webhooks.
10. Add a streaming node with docs/streaming-node-deployment-guide.md.

Contributor Guide: Where to Add New Features

Use these boundaries when enhancing the platform:

Feature type	Add code in
Backend domain logic	nevewatch_backend/src/modules/<feature>/
Backend shared middleware/guards/services	nevewatch_backend/src/common/
Backend env config	nevewatch_backend/src/config/ and ansible/templates/env/
Web admin/store UI	nevewatch_web_app/src/app/
Mobile user UI	nevewatch_mobile/lib/<feature>/
webOS/TV UI	nevewatch_webos/src/app/
Streaming edge behavior	streaming-node/
Server automation	ansible/
Jenkins deployment logic	Jenkinsfile, jenkins-pipelines/, or devops/streaming-node/Jenkinsfile
Monitoring dashboards	monitoring/ or ansible/dashboards/
Security policies	security/ and security-service/
Operator documentation	documentation/ and docs/

Open-Source Readiness Checklist

Before presenting this repository as the first public NeveWatch open-source release:

• Add a root README.md that links to this file, setup docs, contribution guide, license, and security policy.
• Confirm license strategy. The backend package currently declares MIT but is also marked private.
• Remove or sanitize real domains, IP addresses, emails, credentials, tokens, and customer data.
• Move production-like database dumps out of the public repository or replace them with safe seed fixtures.
• Add .env.example files for backend, frontend, mobile, CI, and streaming node.
• Add CONTRIBUTING.md, SECURITY.md, and issue templates.
• Ensure Jenkins examples use placeholders instead of personal domains or private GitLab URLs.
• Add a clear statement that operators are responsible for content licensing and IPTV provider compliance.
• Add reproducible local development instructions for backend, web app, mobile app, and streaming node.
• Add CI tests for backend, web app, mobile app, and streaming-node packages.

Key Runbooks

• Main documentation index: documentation/README.md
• Central host setup: documentation/steps/step-1-central-host-setup.md
• Registry and Jenkins setup: documentation/steps/step-2-registry-jenkins.md
• Jenkins credentials and SSH keys: documentation/steps/step-3-jenkins-credentials-ssh.md
• Add a new client server: documentation/steps/step-4-new-client-server.md
• Streaming node deployment: docs/streaming-node-deployment-guide.md
• Streaming node onboarding: docs/streaming-node-onboarding.md
• Pipeline explanation: documentation/steps/pipeline-monitoring-explained.md