nexus/README.md

# Nexus

Nexus is the operations platform for the Noveria ecosystem. OpenClaw is an
adapter-backed agent runtime, not a dependency of the frontend or domain model.

> CI runs automatically on every push. CD can run **automatically after successful CI**
> on main (patch-bump default) or can be triggered **manually** (workflow_dispatch) with
> full parameter control. Main deploys bump/tag a release; arbitrary `git_ref` deploys
> stay read-only. Rollback and database backup are separate manual workflows.
> See [phases/deployment.md](phases/deployment.md) for full CD documentation.

## Current foundation

- Vue 3, TypeScript, Pinia, Vue Router and Tailwind CSS
- ASP.NET Core 10 REST API (Minimal API pattern)
- Entity Framework Core and PostgreSQL
- JWT owner authentication with rotating refresh sessions
- `IAgentRuntime` abstraction with an OpenClaw adapter (Ollama and NVIDIA removed — OpenClaw-only)
- Responsive dark-mode operations dashboard
- Traefik reverse-proxy with Let's Encrypt TLS on `nexus.noveria.net`

## Local/container start

```bash
cp .env.example .env
# Replace every placeholder, especially POSTGRES_PASSWORD, JWT_KEY,
# OWNER_EMAIL and OWNER_PASSWORD.
docker compose up --build -d
curl http://127.0.0.1:18880/health
```

On an empty database the API creates exactly one owner from `OWNER_EMAIL`,
`OWNER_PASSWORD` and `OWNER_DISPLAY_NAME`. The password must contain at least 10
characters. Existing databases are never overwritten by the bootstrap process.

The API is exposed via Traefik reverse-proxy with automatic Let's Encrypt TLS.
Health checks, rate limiting, and security headers are active.

## Workspace mounts

The API container mounts agent workspaces from the host for file browsing
and the config editor. These are mounted under `/mnt/workspace-{agentId}`:

| Host path | Container mount |
|---|---|
| `/home/projekte_bao/openclaw/data/openclaw/workspace-iris` | `/mnt/workspace-iris` |
| `/home/projekte_bao/openclaw/data/openclaw/workspace-programmer` | `/mnt/workspace-programmer` |
| `/home/projekte_bao/openclaw/data/openclaw/workspace-reviewer` | `/mnt/workspace-reviewer` |
| `/home/projekte_bao/openclaw/data/openclaw/workspace-architekt` | `/mnt/workspace-architekt` |
| `/home/projekte_bao/openclaw/data/openclaw/workspace-researcher` | `/mnt/workspace-researcher` |
| `/home/projekte_bao/openclaw/data/openclaw/workspace-executor` | `/mnt/workspace-executor` |

## Frontend architecture

### Source layout

```
frontend/src/
├── App.vue                # Root shell with sidebar + standalone views
├── main.ts                # App bootstrap
├── router.ts              # Vue Router config
├── types/
│   ├── index.ts           # Re-exports
│   ├── agent.ts           # AgentInfo, AgentDetail, TeamMember
│   ├── config.ts          # ConfigFileInfo, SecurityStatus
│   ├── dashboard.ts       # OperationsSnapshot, RuntimeStatus, etc.
│   └── project.ts         # MemoryFile, DocFile types
├── stores/
│   ├── auth.ts            # Auth store (JWT, login/refresh/logout)
│   └── operations.ts      # Operations store (snapshot, CRUD, approve/reject)
├── services/
│   └── api.ts             # Authenticated fetch wrapper (auto-refresh)
├── composables/
│   └── useTime.ts         # Greeting composable (Morgen/Tag/Abend)
├── views/
│   ├── LoginView.vue
│   ├── DashboardView.vue      # New dashboard (Phase 2)
│   ├── ProjectDetailView.vue
│   ├── SettingsView.vue
│   ├── MemoryView.vue
│   ├── DocsView.vue
│   ├── TeamView.vue
│   ├── SecurityView.vue
│   ├── IncidentsView.vue
│   ├── CalendarView.vue
│   ├── AgentDetailView.vue
│   └── AgentsIndexView.vue
├── components/
│   ├── layout/
│   │   ├── AppSidebar.vue
│   │   └── AppHeader.vue
│   └── dashboard/              # New dashboard components (Phase 2)
│       ├── IrisPanel.vue       # Agent overview + metrics + chat
│       ├── OperationsFeed.vue  # Live activity feed with filters
│       ├── AgendaPanel.vue     # Daily agenda with checkboxes + localStorage
│       ├── ActiveInitiatives.vue  # Project cards with progress
│       └── RecentlyFinished.vue   # Quick status chips
└── ModuleView.vue
```

### App.vue `standaloneViews` whitelist

New views must be registered in the `standaloneViews` computed property in
`App.vue` (line ~34). Without this entry, `RouterView` will not render the
component — the route is valid but the template stays empty.

### New dashboard (Phase 2)

The dashboard was redesigned with a three-column layout:

- **IrisPanel** — Agent avatar/greeting, metrics counters (open tasks, blocked,
  overdue, today), AI suggestions, quick action buttons, and an inline chat box.
- **OperationsFeed** — Searchable/filterable activity feed with colour-coded
  status dots and yesterday/today/week grouping.
- **AgendaPanel** — Daily agenda with checkable items persisted in
  `localStorage` under key `nexus-agenda-done`. Items are sectioned into
  "Heute", "Morgen", and "Überfällig".
- **ActiveInitiatives** — Project initiative cards with progress bars, status
  badges (healthy/attention/blocked/paused/completed), and last activity timestamps.
- **RecentlyFinished** — Horizontally scrollable chip list of recently completed items.

### Authentication

- Passwords use versioned PBKDF2-SHA256 hashes with random salts and 210,000 iterations.
- Access tokens expire after 15 minutes and are held only in browser memory.
- Refresh tokens are random, stored only as SHA-256 hashes in PostgreSQL, rotated on use and checked for reuse.
- The browser receives the refresh token only as a `HttpOnly`, `Secure`, `SameSite=Strict` cookie.
- Login and refresh endpoints are rate-limited per forwarded client IP (5 attempts/minute).
- All `/api/v1` operations routes require a valid access token; `/health` remains public.
- Swagger is enabled only in the Development environment.
- CSRF protection via `X-CSRF-TOKEN` header and `nexus-csrf` cookie (not HttpOnly).

### Security

- Never commit `.env`.
- Generate `JWT_KEY` from at least 32 random bytes.
- Rotate any credential that has appeared in chat before using it.
- Do not expose PostgreSQL or the API container directly.
- Keep OpenClaw behind the `IAgentRuntime` contract.
- Keep the API reachable only through the bundled web proxy or another trusted reverse proxy.

## Frontend routes (SPA)

The SPA uses history-mode routes. Standalone views (whitelisted in App.vue):

| Route | View | Description |
|---|---|---|
| `/login` | LoginView | Owner login |
| `/dashboard` | DashboardView | Operations snapshot with IrisPanel, Feed, Agenda |
| `/memory` | MemoryView | Memory file browser with search |
| `/docs` | DocsView | Documentation file browser |
| `/team` | TeamView | Agent team org map |
| `/security` | SecurityView | Security status center |
| `/projects/:id` | ProjectDetailView | Project detail |
| `/incidents` | IncidentsView | Incident diary |
| `/calendar` | CalendarView | Cron/scheduler overview |
| `/agents` | AgentsIndexView | Agent inventory |
| `/agents/:id` | AgentDetailView | Agent detail + config editor |
| `/settings` | SettingsView | Profile + password management |

Legacy ModuleView routes (not standalone, rendered through `ModuleView.vue`):

| Route | Name | Description |
|---|---|---|
| `/projects` | Projects | Project portfolio |
| `/tasks` | Task Board | Task board |
| `/models` | Models | Provider routing status |
| `/activity` | Activity | Audit timeline |
| `/chat` | Mobile Chat | Owner-chat preview |

## API endpoints

### Health & Auth (public or rate-limited)

| Method | Path | Auth | Description |
|---|---|---|---|
| `GET` | `/health` | No | Health check with runtime + PostgreSQL |
| `GET` | `/api/v1/auth/csrf` | No | Get CSRF token |
| `POST` | `/api/v1/auth/login` | No (rate-limited) | Login with email/password |
| `POST` | `/api/v1/auth/refresh` | No (rate-limited) | Refresh access token |
| `POST` | `/api/v1/auth/logout` | No | Clear refresh token |
| `GET` | `/api/v1/auth/me` | Yes | Current user info |
| `PATCH` | `/api/v1/auth/profile` | Yes | Update display name |
| `POST` | `/api/v1/auth/change-password` | Yes | Change password (min 10 chars) |

### Operations

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/operations/snapshot` | Full operations snapshot (runtime, agents, projects, tasks, activity, metrics) |

### Projects

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/projects` | List all projects |
| `POST` | `/api/v1/projects` | Create project |
| `GET` | `/api/v1/projects/{id}` | Get project detail |
| `PATCH` | `/api/v1/projects/{id}` | Update project (name, description, status) |
| `DELETE` | `/api/v1/projects/{id}` | Delete or archive project (archives if has tasks) |

### Tasks

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/tasks` | List all tasks |
| `POST` | `/api/v1/tasks` | Create task |
| `GET` | `/api/v1/tasks/pending-approval` | Tasks in progress older than 1 hour |
| `PATCH` | `/api/v1/tasks/{id}` | Update task (title, priority, projectId) |
| `PATCH` | `/api/v1/tasks/{id}/state` | Update task state |
| `POST` | `/api/v1/tasks/{id}/approve` | Approve task (in-progress → done) |
| `POST` | `/api/v1/tasks/{id}/reject` | Reject task (in-progress → backlog) |
| `DELETE` | `/api/v1/tasks/{id}` | Delete task (only done/backlog states) |

### Agents

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/agents` | List all agents |
| `GET` | `/api/v1/agents/{id}` | Agent detail (with sub-agents, identity) |
| `GET` | `/api/v1/agents/{id}/activity` | Agent-specific activity (last 50) |
| `POST` | `/api/v1/agents/{id}/command` | Send command to agent |
| `GET` | `/api/v1/agents/{id}/config` | List agent config files (IDENTITY.md, SOUL.md, etc.) |
| `GET` | `/api/v1/agents/{id}/config/{fileName}` | Read config file content |
| `PUT` | `/api/v1/agents/{id}/config/{fileName}` | Save config file (atomic write) |

### Memory & Docs

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/memory` | List memory files (daily + MEMORY.md) |
| `GET` | `/api/v1/memory/search?q=` | Full-text search in memory files |
| `GET` | `/api/v1/memory/{name}` | Get memory file content |
| `GET` | `/api/v1/docs` | List documentation files by category |
| `GET` | `/api/v1/docs/{**path}` | Get doc file content (catch-all) |

### Activity & Team

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/activity` | Paginated activity feed (supports `type`, `sort`, `page`, `pageSize`) |
| `GET` | `/api/v1/routing` | Model routing status |
| `GET` | `/api/v1/team` | Team org map with identity excerpts |
| `GET` | `/api/v1/incidents` | List incident diary entries |
| `GET` | `/api/v1/incidents/{name}` | Get incident detail |
| `GET` | `/api/v1/security/status` | Security configuration status |

### Calendar (Scheduler)

| Method | Path | Description |
|---|---|---|
| `GET` | `/api/v1/calendar` | Cron job overview (gateway or fallback) |
| `GET` | `/api/v1/calendar/upcoming` | Upcoming cron jobs |

### Chat

| Method | Path | Auth | Description |
|---|---|---|---|
| `POST` | `/api/v1/chat` | Yes (rate-limited) | Route message through IAgentRuntime |

Project and task mutations create activity records. The API applies committed EF
Core migrations after PostgreSQL becomes healthy. No destructive endpoints are
implemented on the data layer.

## State machine (tasks)

Tasks follow a simple state machine:

```
Backlog → In progress → Done
Backlog → Blocked → In progress / Done
```

- Only `In progress` or `Blocked` tasks can be approved (→ Done) or rejected (→ Backlog).
- Only `Done` or `Backlog` tasks can be deleted.

## Runtime chat and model routing

`POST /api/v1/chat` routes authenticated owner messages through the
`IAgentRuntime` contract. The browser never receives a Gateway password or model
provider key. Conversation IDs are stable per browser and Iris is the default
agent target.

The configured model-routing policy routes through the OpenClaw Gateway only.
Ollama and NVIDIA providers have been removed. Currently active models:

| Agent | Model |
|-------|-------|
| Iris | `openai/gpt-5.4` |
| Programmer, Executor | `deepseek/deepseek-v4-flash` |
| Reviewer, Architekt, Researcher | `deepseek/deepseek-v4-pro` |

Claude models (Sonnet 4.6, Opus 4.6/4.7/4.8) are available via `claude-cli` backend.

The Settings module reports runtime and provider state without exposing
credentials.

## CI/CD

### CI — Automatic

Every push to `main` triggers `.gitea/workflows/ci.yaml`:
- **Backend**: .NET restore → build → test
- **Frontend**: pnpm install → type-check → test → build
- **Security**: Scan for hardcoded secrets in source code

CI must never break. If it does, Reviewer fixes.

### CD — Auto + Manual (CD v3)

Deployment can happen automatically or manually:

#### Auto-Deploy (after successful CI on main)

- Triggered by `workflow_run` after `CI - Build & Test` succeeds on `main`
- Uses safe defaults: `patch` bump, all services, main ref
- Skips automatically if the triggering commit contains `[skip ci]` (version-bump commits)
- The version-bump commit itself uses `[skip ci]` → no infinite CI→Deploy→Bump→CI loops

#### Manual Deploy (`workflow_dispatch`)

1. DevOps triggers `Deploy to Production` in Gitea Actions (or Iris auto-approves)
2. Chooses version bump type: patch (default) / minor / major
3. Optionally scopes to a single service or specific git ref
4. Workflow bumps VERSION, creates git tag, builds and deploys
5. Health check + smoke test verify the deployment

#### Rollback (`workflow_dispatch`)

1. DevOps triggers `Rollback to Previous Version` in Gitea Actions
2. Enters target git tag (e.g. `v0.2.49`) + confirmation `ROLLBACK`
3. Workflow checks out the tag, rebuilds with `--no-cache`, redeploys
4. Health check + smoke test verify the rollback

#### Database Backup (`workflow_dispatch`)

1. DevOps triggers `Database Backup` in Gitea Actions
2. Optionally also copies backup to a host path (`/home/projekte_bao/backups`)
3. Workflow dumps PostgreSQL via `pg_dumpall`, gzips, and uploads as a Gitea artifact
4. Artifacts are retained for 90 days (configurable)
5. Optional nightly schedule (uncomment the cron trigger in `backup.yaml`)

#### Failure Handling

When deploy or rollback fails:
- **DevOps (Architekt)** analyses the error
- **Reviewer (Code-Fixer)** fixes the problem
- **DevOps** re-deploys to verify the fix

The workflow outputs a formatted handoff message with the job URL.

Full CD documentation: [phases/deployment.md](phases/deployment.md)