# @serve.zone/dcrouter-web

Web-based Operations Dashboard for DcRouter. 🖥️

A modern, reactive web application for monitoring and managing your DcRouter instance in real-time. Built with web components using [@design.estate/dees-element](https://code.foss.global/design.estate/dees-element) and [@design.estate/dees-catalog](https://code.foss.global/design.estate/dees-catalog).

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Features

### 🔐 Secure Authentication
- JWT-based login with persistent sessions (IndexedDB)
- Automatic session expiry detection and cleanup
- Secure username/password authentication

### 📊 Overview Dashboard
- Real-time server statistics (CPU, memory, uptime)
- Active connection counts and email throughput
- DNS query metrics and RADIUS session tracking
- Auto-refreshing with configurable intervals

### 🌐 Network View
- Active connection monitoring with real-time data from SmartProxy
- Top connected IPs with connection counts and percentages
- Throughput rates (inbound/outbound in kbit/s, Mbit/s, Gbit/s)
- Traffic chart with selectable time ranges

### 📧 Email Management
- **Queued** — Emails pending delivery with queue position
- **Sent** — Successfully delivered emails with timestamps
- **Failed** — Failed emails with resend capability
- **Security** — Security incidents from email processing
- Bounce record management and suppression list controls

### 🔐 Certificate Management
- Domain-centric certificate overview with status indicators
- Certificate source tracking (ACME, provision function, static)
- Expiry date monitoring and alerts
- Per-domain backoff status for failed provisions
- One-click reprovisioning per domain
- Certificate import, export, and deletion

### 🌍 Remote Ingress Management
- Edge node registration with name, ports, and tags
- Real-time connection status (connected/disconnected/disabled)
- Public IP and active tunnel count per edge
- Auto-derived port display with manual/derived breakdown
- **Connection token generation** — one-click "Copy Token" for easy edge provisioning
- Enable/disable, edit, secret regeneration, and delete actions

### 🔐 VPN Management
- VPN server status with forwarding mode, subnet, and WireGuard port
- Client registration table with create, enable/disable, and delete actions
- WireGuard config download, clipboard copy, and **QR code display** on client creation
- QR code export for existing clients — scan with WireGuard mobile app (iOS/Android)
- Per-client telemetry (bytes sent/received, keepalives)
- Server public key display for manual client configuration

### 📜 Log Viewer
- Real-time log streaming
- Filter by log level (error, warning, info, debug)
- Search and time-range selection

### 🛣️ Route & API Token Management
- Programmatic route CRUD with enable/disable and override controls
- API token creation, revocation, and scope management
- Routes tab and API Tokens tab in unified view

### 🛡️ Security Profiles & Network Targets
- Create, edit, and delete reusable security profiles (IP allow/block lists, rate limits, max connections)
- Create, edit, and delete reusable network targets (host:port destinations)
- In-row and context menu actions for quick editing
- Changes propagate automatically to all referencing routes

### ⚙️ Configuration
- Read-only display of current system configuration
- Status badges for boolean values (enabled/disabled)
- Array values displayed as pills with counts
- Section icons and formatted byte/time values

### 🛡️ Security Dashboard
- IP reputation monitoring
- Rate limit status across domains
- Blocked connection tracking
- Security event timeline

## Architecture

### Technology Stack

| Layer | Package | Purpose |
|-------|---------|---------|
| **Components** | `@design.estate/dees-element` | Web component framework (lit-element based) |
| **UI Kit** | `@design.estate/dees-catalog` | Pre-built components (tables, charts, forms, app shell) |
| **State** | `@push.rocks/smartstate` | Reactive state management with persistent/soft modes |
| **Routing** | Client-side router | URL-synchronized view navigation |
| **API** | `@api.global/typedrequest` | Type-safe communication with OpsServer |
| **Types** | `@serve.zone/dcrouter-interfaces` | Shared TypedRequest interface definitions |

### Component Structure

```
ts_web/
├── index.ts                  # Entry point — renders <ops-dashboard>
├── appstate.ts               # State management (all state parts + actions)
├── router.ts                 # Client-side routing (AppRouter)
├── plugins.ts                # Dependency imports
└── elements/
    ├── ops-dashboard.ts      # Main app shell
    ├── ops-view-overview.ts  # Overview statistics
    ├── ops-view-network.ts   # Network monitoring
    ├── ops-view-emails.ts    # Email queue management
    ├── ops-view-certificates.ts  # Certificate overview & reprovisioning
    ├── ops-view-remoteingress.ts # Remote ingress edge management
    ├── ops-view-vpn.ts       # VPN client management
    ├── ops-view-logs.ts      # Log viewer
    ├── ops-view-routes.ts    # Route & API token management
    ├── ops-view-config.ts    # Configuration display
    ├── ops-view-security.ts  # Security dashboard
    └── shared/
        ├── css.ts            # Shared styles
        └── ops-sectionheading.ts  # Section heading component
```

### State Management

The app uses `@push.rocks/smartstate` v2.3+ with multiple state parts, scheduled actions with `autoPause: 'visibility'`, and batched updates:

| State Part | Mode | Description |
|-----------|------|-------------|
| `loginStatePart` | Persistent (IndexedDB) | JWT identity and login status |
| `statsStatePart` | Soft (memory) | Server, email, DNS, security, RADIUS, VPN metrics |
| `configStatePart` | Soft | Current system configuration |
| `uiStatePart` | Soft | Active view, sidebar, auto-refresh, theme |
| `logStatePart` | Soft | Recent logs, streaming status, filters |
| `networkStatePart` | Soft | Connections, IPs, throughput rates |
| `emailOpsStatePart` | Soft | Email queues, bounces, suppression list |
| `certificateStatePart` | Soft | Certificate list, summary, loading state |
| `remoteIngressStatePart` | Soft | Edge list, statuses, new edge secret |
| `vpnStatePart` | Soft | VPN clients, server status, new client config |

### Tab Visibility Optimization

The dashboard automatically pauses all background activity when the browser tab is hidden and resumes when visible:

- **Auto-refresh polling** uses `createScheduledAction` with `autoPause: 'visibility'` — stops HTTP requests while the tab is sleeping
- **In-flight guard** prevents concurrent refresh requests from piling up
- **WebSocket connection** disconnects when hidden and reconnects when visible, preventing log entry accumulation
- **Network traffic timer** pauses chart updates when the tab is backgrounded
- **Log entry batching** — incoming WebSocket log pushes are buffered and flushed once per animation frame to avoid per-entry re-renders

### Actions

```typescript
// Authentication
loginAction(username, password)    // JWT login
logoutAction()                     // Clear session

// Data fetching (auto-refresh compatible)
fetchAllStatsAction()              // Server + email + DNS + security stats
fetchConfigurationAction()         // System configuration
fetchRecentLogsAction()            // Log entries
fetchNetworkStatsAction()          // Connection + throughput data

// Email operations
fetchQueuedEmailsAction()          // Pending emails
fetchSentEmailsAction()            // Delivered emails
fetchFailedEmailsAction()          // Failed emails
fetchSecurityIncidentsAction()     // Security events
fetchBounceRecordsAction()         // Bounce records
resendEmailAction(emailId)         // Re-queue failed email
removeFromSuppressionAction(email) // Remove from suppression list

// Certificates
fetchCertificateOverviewAction()   // All certificates with summary
reprovisionCertificateAction(domain) // Reprovision a certificate
deleteCertificateAction(domain)    // Delete a certificate
importCertificateAction(cert)      // Import a certificate
fetchCertificateExport(domain)     // Export (standalone function)

// Remote Ingress
fetchRemoteIngressAction()         // Edges + statuses
createRemoteIngressAction(data)    // Create new edge
updateRemoteIngressAction(data)    // Update edge settings
deleteRemoteIngressAction(id)      // Remove edge
regenerateRemoteIngressSecretAction(id) // New secret
toggleRemoteIngressAction(id, enabled)  // Enable/disable
clearNewEdgeSecretAction()         // Dismiss secret banner
fetchConnectionToken(edgeId)       // Get connection token (standalone function)

// VPN
fetchVpnAction()                   // Clients + server status
createVpnClientAction(data)        // Create new VPN client
deleteVpnClientAction(clientId)    // Remove VPN client
toggleVpnClientAction(id, enabled) // Enable/disable
clearNewClientConfigAction()       // Dismiss config banner
```

### Client-Side Routing

```
/overview        → Overview dashboard
/network         → Network monitoring
/emails          → Email management
  /emails/queued    → Queued emails
  /emails/sent      → Sent emails
  /emails/failed    → Failed emails
  /emails/security  → Security incidents
/certificates    → Certificate management
/remoteingress   → Remote ingress edge management
/vpn             → VPN client management
/routes          → Route & API token management
/logs            → Log viewer
/configuration   → System configuration
/security        → Security dashboard
```

URL state is synchronized with the UI — bookmarking and deep linking fully supported.

## Development

### Running Locally

Start DcRouter with OpsServer enabled:

```typescript
import { DcRouter } from '@serve.zone/dcrouter';

const router = new DcRouter({
  // OpsServer starts automatically on port 3000
  smartProxyConfig: { routes: [/* your routes */] }
});

await router.start();
// Dashboard at http://localhost:3000
```

### Building

```bash
# Build the bundle
pnpm run bundle

# Watch for development (auto-rebuild + restart)
pnpm run watch
```

The bundle is output to `./dist_serve/bundle.js` and served by the OpsServer.

### Adding a New View

1. Create a view component in `elements/`:
```typescript
import { DeesElement, customElement, html, css } from '@design.estate/dees-element';

@customElement('ops-view-myview')
export class OpsViewMyView extends DeesElement {
  public static styles = [css`:host { display: block; padding: 24px; }`];

  public render() {
    return html`<ops-sectionheading>My View</ops-sectionheading>`;
  }
}
```

2. Add it to the dashboard tabs in `ops-dashboard.ts`
3. Add the route in `router.ts`
4. Add any state management in `appstate.ts`

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](../license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH  
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.
