Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 73 Pull Requests 9 Actions Packages Projects Releases Wiki Activity

Web Console: Architecture and information architecture (Phase 1) #632

New Issue
Open
opened 2026-07-10 14:38:12 -05:00 by jcwalker3 · 1 comment
jcwalker3 commented 2026-07-10 14:38:12 -05:00
Owner
Copy Link
Copy Source

Problem statement

The MVP web UI (#425–#436) exists under webui/ but lacks a durable architecture document for the expanded MCP Control Plane Web Console: layers, API versioning, page map, authority boundaries, phase gates, and how console state relates to Gitea, control-plane DB, MCP tools, and observability bridges.

User and operational impact

Without architecture, implementers reinvent boundaries, duplicate MVP routes, or wire privileged actions before auth/audit exists. Future LLMs cannot retrieve a single source for console design.

Scope

  • Document console product surface vs MVP (webui/ routes today).
  • Define layers: browser UI, JSON APIs, domain loaders, control-plane DB, Gitea/MCP, external providers.
  • Define Phase 1–4 capability gates (read-only → controlled actions → orchestration → insights).
  • Define route/API naming conventions and versioning (/api/v1/...).
  • Map each epic capability area to owning modules and child issues under #631.
  • Specify source-of-truth rules (Gitea records; DB coordinates; console projects).

Explicit non-goals

  • Do not implement UI or APIs in this issue.
  • Do not redesign closed MVP features from scratch.
  • Do not change production deployment topology beyond documenting targets.

Required implementation investigation

Inspect webui/app.py, loaders/views, docs/webui-*.md, docs/architecture/mcp-allocator-control-plane-observability-adr.md, docs/safety-model.md, docs/tool-boundaries.md, epic #631, MVP #425.

Proposed architecture or implementation direction

  • ADR-style doc under docs/architecture/ + short link from docs/webui-local-dev.md.
  • Mermaid or table for request flow: UI → API → loaders → (Gitea|CP-DB|filesystem) with redaction boundary.
  • Explicit “no secrets to browser” and “no ungated mutations” invariants.

Security and workflow-safety requirements

Architecture must require fail-closed auth for future writes, secret redaction defaults, and contamination surfacing (#630).

Acceptance criteria

  1. Architecture doc merged (or PR linked) covering layers, authority, phases, API versioning, page map.
  2. Each #631 child maps to at least one architectural component.
  3. Document states MVP #425–#436 as foundation.
  4. Explicit forbidden paths: raw provider incidents as work, browser-held tokens, process-kill recovery.
  5. Controller can approve architecture without reading chat history.

Required tests

  • Doc existence check or architecture-link test if repo uses doc gates; otherwise review checklist in PR template comment.
  • Linkage: issue references #631 and is referenced from epic.

Observability and audit requirements

Record decision rationale and open questions in the ADR; link follow-up issues for unresolved choices.

Dependencies and linkage

Canonical issue state

STATE: ready-for-author
WHO_IS_NEXT: author
NEXT_ACTION: Claim #N, write architecture ADR extending webui MVP
NEXT_PROMPT: Author implements architecture doc only; open PR; stop for review

Required final evidence

PR with ADR + epic cross-links; no feature code required.

Required final response and handoff expectations

Brief: ADR path, PR number, next = reviewer. Full proof in Gitea comments only.

## Problem statement The MVP web UI (#425–#436) exists under `webui/` but lacks a durable architecture document for the expanded **MCP Control Plane Web Console**: layers, API versioning, page map, authority boundaries, phase gates, and how console state relates to Gitea, control-plane DB, MCP tools, and observability bridges. ## User and operational impact Without architecture, implementers reinvent boundaries, duplicate MVP routes, or wire privileged actions before auth/audit exists. Future LLMs cannot retrieve a single source for console design. ## Scope * Document console product surface vs MVP (`webui/` routes today). * Define layers: browser UI, JSON APIs, domain loaders, control-plane DB, Gitea/MCP, external providers. * Define Phase 1–4 capability gates (read-only → controlled actions → orchestration → insights). * Define route/API naming conventions and versioning (`/api/v1/...`). * Map each epic capability area to owning modules and child issues under #631. * Specify source-of-truth rules (Gitea records; DB coordinates; console projects). ## Explicit non-goals * Do not implement UI or APIs in this issue. * Do not redesign closed MVP features from scratch. * Do not change production deployment topology beyond documenting targets. ## Required implementation investigation Inspect `webui/app.py`, loaders/views, `docs/webui-*.md`, `docs/architecture/mcp-allocator-control-plane-observability-adr.md`, `docs/safety-model.md`, `docs/tool-boundaries.md`, epic #631, MVP #425. ## Proposed architecture or implementation direction * ADR-style doc under `docs/architecture/` + short link from `docs/webui-local-dev.md`. * Mermaid or table for request flow: UI → API → loaders → (Gitea|CP-DB|filesystem) with redaction boundary. * Explicit “no secrets to browser” and “no ungated mutations” invariants. ## Security and workflow-safety requirements Architecture must require fail-closed auth for future writes, secret redaction defaults, and contamination surfacing (#630). ## Acceptance criteria 1. Architecture doc merged (or PR linked) covering layers, authority, phases, API versioning, page map. 2. Each #631 child maps to at least one architectural component. 3. Document states MVP #425–#436 as foundation. 4. Explicit forbidden paths: raw provider incidents as work, browser-held tokens, process-kill recovery. 5. Controller can approve architecture without reading chat history. ## Required tests * Doc existence check or architecture-link test if repo uses doc gates; otherwise review checklist in PR template comment. * Linkage: issue references #631 and is referenced from epic. ## Observability and audit requirements Record decision rationale and open questions in the ADR; link follow-up issues for unresolved choices. ## Dependencies and linkage * Parent: #631 * Foundation: #425–#436 * Related ADR: control-plane observability ADR; #628 orchestration umbrella * Blocks: most Phase 1 API/UI issues should reference this as soft dependency ## Canonical issue state ```text STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Claim #N, write architecture ADR extending webui MVP NEXT_PROMPT: Author implements architecture doc only; open PR; stop for review ``` ## Required final evidence PR with ADR + epic cross-links; no feature code required. ## Required final response and handoff expectations Brief: ADR path, PR number, next = reviewer. Full proof in Gitea comments only.
jcwalker3 commented 2026-07-10 14:48:52 -05:00
Author
Owner
Copy Link
Copy Source

Canonical Issue State

STATE:
ready-for-author

WHO_IS_NEXT:
author

NEXT_ACTION:
Implement this Phase 1 issue only; link PR to vision #652 and roadmap #653

NEXT_PROMPT:

AUTHOR prgs Scaled-Tech-Consulting/Gitea-Tools. Implement #632 (Architecture).
Vision #652 · Roadmap #653 Phase 1 · Umbrella #631 · Foundation #425–#436.
Lock #632; branches/ worktree; architecture ADR only; PR; stop. Closing this issue does not complete #652 vision.

WHAT_HAPPENED:
Linkage update: this issue is Phase 1 of #653 and part of vision #652. Not recreated.

WHY:
Planning package requires explicit vision/roadmap links on initial implementation batch.

RELATED_ISSUES:
#652 #653 #631 #425–#436; soft-blocks #633–#641

RELATED_PRS:
none

BLOCKERS:
none

VALIDATION:
Existing issue retained; no duplicate

LAST_UPDATED_BY:
jcwalker3 / prgs-author / author / 2026-07-10

## Canonical Issue State STATE: ready-for-author WHO_IS_NEXT: author NEXT_ACTION: Implement this Phase 1 issue only; link PR to vision #652 and roadmap #653 NEXT_PROMPT: ```text AUTHOR prgs Scaled-Tech-Consulting/Gitea-Tools. Implement #632 (Architecture). Vision #652 · Roadmap #653 Phase 1 · Umbrella #631 · Foundation #425–#436. Lock #632; branches/ worktree; architecture ADR only; PR; stop. Closing this issue does not complete #652 vision. ``` WHAT_HAPPENED: Linkage update: this issue is Phase 1 of #653 and part of vision #652. Not recreated. WHY: Planning package requires explicit vision/roadmap links on initial implementation batch. RELATED_ISSUES: #652 #653 #631 #425–#436; soft-blocks #633–#641 RELATED_PRS: none BLOCKERS: none VALIDATION: Existing issue retained; no duplicate LAST_UPDATED_BY: jcwalker3 / prgs-author / author / 2026-07-10
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
allocator
Controller-owned work allocator
 anti-stomp
Prevent concurrent LLM session stomping
 architecture
Architecture / structural design
 bug
chore
codex
OpenAI Codex client / workflow session surface
 concurrency
Concurrent session safety
 contamination
Workflow or session contamination incident
 control-plane
MCP control-plane coordination and allocation authority
 dashboard
MCP operational dashboard/queue view
 database
Internal coordination storage (SQLite/Postgres)
 design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
incident
Operational or process incident requiring durable audit trail
 incident-bridge
Sentry-to-Gitea incident bridging
 integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 leases
Lease adopt/release/expire lifecycle
 mcp
MCP server / tooling
 mcp-health
MCP namespace and runtime health
 mcp-menu
MCP menu surface
 multi-project
Work spanning multiple monitoring projects or Gitea repos
 mutating
Mutating action; requires gating
 nice-to-have
observability
Observability, metrics, traces, error reporting
 portability
Cross-platform / portability
 preflight
Shared preflight gates before mutation
 protected-branch
Protected branch / stable-branch policy concern
 queue
Work queue visibility and allocation
 read-only
Read-only, no mutation
 reconnect
MCP client reconnect/reload recovery path
 recovery
Recovery paths for stale/foreign leases
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 resumable-review
Persist and resume prepared review verdicts across sessions
 reviewer
Reviewer workflow tooling
 roadmap
Roadmap / umbrella issue
 safety
Safety rails and fail-closed mutation guards
 security
Security / trust boundary
 self-hosted
Self-hosted infrastructure integration
 sentry
Sentry error monitoring integration
 stale-runtime
Stale backend daemon / runtime-vs-master parity failures
 status:blocked
Issue is blocked
 status:in-progress
Issue is being worked on
 status:pr-open
Issue has an open pull request
 status:ready
Issue is ready for work
 terminal-lock
Terminal review lock (#332) path
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 type:bug
Bug or defect
 type:feature
Feature or enhancement
 type:feature
Feature or enhancement
 type:guardrail
Safety gate or guardrail
 visibility
Workflow state visibility for LLMs/operators
 workflow
Cross-tool workflow
 workflow-hardening
LLM workflow coordination hardening
 workflow-hardening
LLM workflow coordination hardening
No labels dashboard documentation status:ready type:feature workflow-hardening
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#632