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/CD auto-deploy enabled — every push to main triggers build → test → deploy.

## 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
- `IModelProvider` abstractions for Ollama and NVIDIA
- Responsive dark-mode operations dashboard
- Container-only entry point on `127.0.0.1:18880`

## 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 14
characters. Existing databases are never overwritten by the bootstrap process.

The web service is loopback-only. Public reverse-proxy activation for
`nexus.noveria.net` remains a separate infrastructure change and must terminate
TLS before forwarding to port `18880`.

## 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 |
|---|---|
| `/opt/openclaw/data/openclaw/workspace-iris` | `/mnt/workspace-iris` |
| `/opt/openclaw/data/openclaw/workspace-programmer` | `/mnt/workspace-programmer` |
| `/opt/openclaw/data/openclaw/workspace-reviewer` | `/mnt/workspace-reviewer` |
| `/opt/openclaw/data/openclaw/workspace-architekt` | `/mnt/workspace-architekt` |
| `/opt/openclaw/data/openclaw/workspace-researcher` | `/mnt/workspace-researcher` |
| `/opt/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 is:

1. `qwen3:4b` through Ollama for routine and monitoring work
2. `moonshotai/kimi-k2.6` through NVIDIA for primary work
3. `gpt-5.5` through OpenClaw for strategic and critical review

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