dcrouter/ts_web/readme.md

# @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

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

### ⚙️ 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-logs.ts      # Log viewer
    ├── 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` with multiple state parts:

| State Part | Mode | Description |
|-----------|------|-------------|
| `loginStatePart` | Persistent (IndexedDB) | JWT identity and login status |
| `statsStatePart` | Soft (memory) | Server, email, DNS, security 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 |

### 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
```

### 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
/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.