diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c17f62b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,188 @@ +# AGENTS.md — ForgeBucket AI Agent Guide + +This file is for AI coding agents (Claude Code, GitHub Copilot, etc.) working in this repository. Read it before making changes. + +--- + +## Mission + +ForgeBucket is a **unified operating system for software delivery** — not a Git repository viewer with CI attached. The guiding philosophy: + +> Repositories are runtime systems. The dashboard is a command center. GitOps is first-class. + +Every feature decision should answer: does this reduce cognitive load? Does this improve operational awareness? Does this improve developer flow? + +The full product vision lives in [`ai_agent_master_prompt_for_building_modern_git_platform.md`](ai_agent_master_prompt_for_building_modern_git_platform.md). + +--- + +## Architecture Map + +``` +cmd/forgebucket/ — binary entry point (main.go) +internal/ + api/ + router.go — Chi router, all route definitions (~26 routes) + middleware/ — auth, CSRF, RBAC, logging + handlers/ — one file per domain (repo, pr, issue, auth, user, ssh...) + domain/ + git/ — sanitized git binary wrapper (exec.Command only, no shell) + federation/ — ActivityPub / ForgeFed (DATA LAYER ONLY — no handlers yet) + ci/ — CI orchestrator (EMPTY — Phase 2 stub) + models/ — XORM structs + 7 migration files + config/ — ENV-driven config, fails fast on missing secrets +web/ — //go:embed target for the built React SPA +frontend/ + src/ + pages/ — 20 route-level page components + components/ — shared UI (AppShell, Sidebar, Header, DiffViewer, etc.) + ui/ + tokens.ts — SINGLE SOURCE OF TRUTH for all design tokens + hooks/ — custom React hooks + api/ — typed API client (fetch wrappers) +``` + +**Middleware chain — this order is fixed, do not reorder:** +``` +Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler +``` + +--- + +## Current Phase Status + +Understand the phases before adding code — don't build Phase 3 infrastructure when Phase 2 is incomplete. + +| Phase | Scope | Status | +|-------|-------|--------| +| 1 | Auth, Git HTTP, repos, PRs, issues, RBAC, webhooks model, LFS, design system, 20-page SPA | **Complete** | +| 2 | CI/CD orchestrator, runner manager, pipeline DAG visualization, artifact registry | **Active — `internal/domain/ci/` is the stub** | +| 3 | GitOps controller, environments, drift detection, federation handlers, observability, audit log | Planned | +| 4 | Command palette, AI diagnostics, signed artifacts, package registry | Planned | + +Do not implement Phase 3+ features without explicit discussion. The `domain/federation/` and `domain/ci/` directories are intentional stubs. + +--- + +## Go Conventions + +### Git commands — critical rule +Always use `exec.Command("git", arg1, arg2, ...)` with **discrete arguments**. Never build a shell string from user input. + +```go +// CORRECT +cmd := exec.Command("git", "clone", "--bare", repoURL, destPath) + +// WRONG — never do this +cmd := exec.Command("sh", "-c", "git clone "+userInput) +``` + +This rule is non-negotiable. It prevents command injection. + +### Router / handlers +- Chi router. Route definitions in `internal/api/router.go`. +- One handler file per domain area. Keep handlers thin — business logic belongs in domain packages. +- All POST/PUT/DELETE routes require `X-CSRF-Token` header matching the session cookie. The middleware enforces this, but don't remove it from routes. + +### Database +- XORM for all DB access. Structs in `internal/models/`. +- Migrations are numbered files in `internal/models/migrations/`. Always add a new migration file; never edit existing ones. +- No raw SQL strings built from user input. + +### Secrets and config +- All secrets come from environment variables via `internal/config/`. +- Never hardcode secrets, tokens, or credentials anywhere. +- `SESSION_SECRET` ≥ 32 chars. `CSRF_SECRET` = exactly 32 chars. + +### Error handling +- Return errors up the call stack. Don't swallow them silently. +- HTTP handlers use consistent JSON error responses — follow the pattern in existing handlers. + +--- + +## TypeScript / React Conventions + +### Design tokens — critical rule +All spacing, color, and sizing values must come from `frontend/src/ui/tokens.ts`. Do not introduce new hardcoded pixel values or color hex codes. + +```tsx +// CORRECT — use token classes via Tailwind +
+ +// WRONG — arbitrary values +
+``` + +### Grid system +- Base unit: 8px. All spacing is multiples of 4px (`xs`) or 8px (`sm`). +- Touch targets: 44px minimum height/width on all interactive elements (buttons, links, icon buttons). + +### Dark mode +- Use Tailwind v4 `@variant dark` — not hardcoded dark: classes unless inside a component that explicitly handles both. +- Colors must work in both light and dark modes. Test both. + +### Component patterns +- `AppShell` wraps all authenticated pages. Don't bypass it. +- `Sidebar` has three states: expanded (320px), collapsed (56px), mobile bottom bar. Respect all three. +- Mobile-first: design for 375px, enhance for 1440px. Use the `BottomTabBar` for mobile nav — don't add new nav patterns. +- Loading states: use `Skeleton` components for perceived performance, not spinners. +- Mobile code review: use the `MobileComment` bottom-sheet pattern — not modals. + +### API calls +- Use the typed API client in `frontend/src/api/` — don't write raw `fetch` calls in components. +- Always include `X-CSRF-Token` header on mutating requests. + +--- + +## What NOT to Do + +- **No shell string injection** — see Go conventions above +- **No hardcoded secrets** — everything via env +- **No skipping CSRF** — all mutating routes require it +- **No arbitrary design values** — tokens.ts is the law +- **No Phase 3+ features without discussion** — don't wire up GitOps, federation handlers, or the command palette until Phase 2 is complete +- **No new color tokens** — if the design requires a new color, discuss it; don't invent one +- **No modal-heavy UX** — this platform uses progressive disclosure; avoid deep modal chains +- **No YAML-centric UI** — pipeline and environment config should feel operational, not config-file editing + +--- + +## Testing + +```bash +make test # Go tests (go test ./...) + Vitest (frontend unit tests) +make lint # go vet + ESLint +``` + +- Go: test files live alongside source files (`*_test.go`) +- Frontend: Vitest for unit tests, component tests alongside components +- All UI changes must be manually verified at 1440px desktop and 375px mobile + +--- + +## Key Files Reference + +| File | Purpose | +|------|---------| +| `internal/api/router.go` | All route definitions — start here for backend | +| `internal/models/` | XORM models + migrations — all DB schemas | +| `internal/config/config.go` | Env-driven config, required vars | +| `internal/domain/git/` | Git binary wrapper — safe exec patterns | +| `frontend/src/ui/tokens.ts` | Design token source of truth | +| `frontend/src/components/AppShell.tsx` | Root layout wrapper | +| `frontend/src/components/Sidebar.tsx` | 3-state navigation sidebar | +| `frontend/src/pages/` | All 20 route-level pages | +| `frontend/src/api/` | Typed API client | +| `.env.example` | All required environment variables | +| `CLAUDE.md` | Developer guide (rules overlap with this file — CLAUDE.md takes precedence on conflicts) | + +--- + +## Running Locally + +```bash +cp .env.example .env # fill SESSION_SECRET and CSRF_SECRET +make docker-up # PostgreSQL via Docker Compose +make migrate # run XORM migrations +make dev # Go :8080 + Vite :5173 +``` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..a843a10 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,102 @@ +# Changelog + +All notable changes to ForgeBucket are documented here. + +Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +--- + +## [Unreleased] + +### Planned — Phase 2 (CI/CD) +- CI orchestrator with DAG pipeline execution +- Runner manager (Docker, Kubernetes, Firecracker backends) +- Pipeline DAG visualization (visual dependency graph with live execution state) +- Build artifact storage and retention policies +- Forgejo Actions gRPC integration +- Flaky test detection +- Pipeline log viewer (collapsible, filterable, syntax-highlighted) +- Matrix builds and reusable workflow templates +- Concurrency controls and pipeline cancellation + +### Planned — Phase 3 (GitOps + Observability + Federation) +- GitOps controller with reconciliation loops +- Environment management and topology visualization +- Drift detection and sync status +- Deployment promotion workflows (dev → staging → production) +- Rollback visualization and one-click rollbacks +- Canary and blue/green deployment support +- Unified operational timeline (commits + deployments + incidents + CI failures merged) +- ActivityPub / ForgeFed federation handlers (inbox, outbox, cross-instance PRs) +- Audit log (all administrative and git-over-HTTP actions) +- Secret scanning and dependency vulnerability scanning + +--- + +## [0.1.0] — 2026-05-11 + +Initial development milestone. Core Git hosting, collaboration, and frontend SPA are functional. + +### Added — Authentication & Security +- User registration and login with secure session cookies +- CSRF protection on all mutating routes via `X-CSRF-Token` header +- Middleware chain: Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler +- SSH key management per user +- OIDC / OAuth2 optional integration (configurable via env) +- Scoped access tokens with optional expiration dates +- Repository deploy keys (read-only or read-write HTTP tokens) +- ENV-driven config with fail-fast validation on missing secrets + +### Added — Git Hosting +- Smart HTTP transport (git clone, push, pull over HTTP) +- AGit protocol support (`refs/for/` push for instant PR creation without branch switching) +- Branch management (list, create, delete, default branch configuration) +- Commit log and diff viewing +- Git LFS per-repository (configurable file size limits, locking) +- Branch protection rules (force-push blocking, required reviews) +- Repository visibility (public / private) + +### Added — Collaboration +- Pull requests (open / merged / closed states) with author tracking +- Issues (open / closed) +- Reviewer assignment (default reviewer per repo, per-PR reviewer assignment) +- Merge strategy selection per repository (merge commit / squash / rebase) +- Branching model configuration (feature / bugfix / release / hotfix prefixes) +- PR default description templates (per-repo) +- Excluded files from diffs (glob pattern configuration) +- Webhook system with event filtering (push, pull_request, issue) +- Repository member RBAC (read / write / admin roles) + +### Added — Frontend SPA +- React 18 + TypeScript + Vite, embedded into Go binary via `//go:embed` +- 20 route-level pages: Login, Register, Dashboard, Repos, CreateRepo, ImportRepo, Repo, RepoSettings, Blob, Commits, Branches, RepoIssues, RepoPRs, CreatePR, PRDetail, Starred, PRs (cross-repo), Pipelines (placeholder), Explore, Profile, Settings +- AppShell layout wrapper for all authenticated pages +- Triple-state sidebar: expanded (320px) / collapsed (56px) / mobile bottom bar +- Mobile-first responsive design (375px → 1440px) +- DiffViewer: side-by-side and unified views with syntax highlighting +- MobileComment: bottom-sheet overlay for inline code review on mobile +- TreeBrowser: repository file tree navigation +- PipelineWaterfall: placeholder pipeline visualization component +- Skeleton loading states for perceived performance + +### Added — Design System +- Custom semantic token palette in `frontend/src/ui/tokens.ts` +- Full dark/light mode support via Tailwind CSS v4 `@variant dark` +- Brand colors: `#0052CC` (light) / `#3B82F6` (dark) +- 8px grid system (xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px, xxl: 48px) +- 44px minimum touch targets on all interactive elements (WCAG 2.5.5) +- Consistent border radius scale (subtle 3–8px, full 9999px) +- System font stack (Segoe UI, Roboto, sans-serif) + +### Added — Infrastructure +- PostgreSQL + XORM with 7 migration files covering: users, repositories, issues, SSH keys, access tokens, deploy keys, workflows, and LFS settings +- ActivityPub actor data model (FederationActor with inbox/outbox URLs and RSA key pairs) — data layer only +- Docker Compose setup for local PostgreSQL +- Makefile targets: dev, build, migrate, test, lint, docker-up +- WebSockets foundation for live logs and notifications + +--- + +[Unreleased]: https://github.com/forgeo/forgebucket/compare/v0.1.0...HEAD +[0.1.0]: https://github.com/forgeo/forgebucket/releases/tag/v0.1.0 diff --git a/README.md b/README.md index 794c93d..e5e9dfd 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,231 @@ -# ForgeBucket 🛡️🪣 +# ForgeBucket -**Sovereign Federation meets Enterprise Design.** +> A unified operating system for software delivery — not just a Git host. -ForgeBucket is a production-ready, federated git collaboration platform. It combines the high-performance, lightweight Go engine of **Forgejo** with the sophisticated, high-density UI/UX of **Bitbucket**, optimized for a "Responsive-First, Access Anywhere" experience. +ForgeBucket is a self-hosted, federated developer operations platform. Where other Git platforms show you a list of files, ForgeBucket surfaces deployments, pipeline health, environment drift, and operational context directly alongside your code. Repositories are runtime systems. The dashboard is a command center. + +**Status:** Early development. Core Git hosting, collaboration, and auth are functional. CI/CD and GitOps integrations are next. --- -## 🚀 The Vision +## What Makes It Different -ForgeBucket aims to provide developers with a world-class code review and project management experience without sacrificing data sovereignty. It bridges the gap between community-driven open-source software and enterprise-grade usability. - -- **Engine:** Built on the Forgejo/Gitea ecosystem. -- **Interface:** Powered by Atlassian Design System (ADS) principles. -- **Connectivity:** Full ActivityPub (ForgeFed) integration for a decentralized git world. +| Principle | What it means | +|-----------|---------------| +| **Repositories are runtime systems** | Repo pages show deployments, environments, health, and risk — not just a file tree | +| **Operational awareness by default** | Failing pipelines, stale PRs, security alerts, and environment drift surface without digging | +| **GitOps is first-class** | Git is the source of truth for deployment state, rollbacks, and environment promotion | +| **Keyboard-first UX** | Global command palette, minimal navigation depth, low cognitive load | +| **Federated by design** | ActivityPub (ForgeFed) for cross-instance pull requests and collaboration | +| **Sovereign** | Fully self-hostable — your code, your infrastructure, your keys | --- -## 🛠️ Tech Stack +## Feature Status -### Backend & Core +### Core Platform +| Feature | Status | +|---------|--------| +| User auth (registration, login, sessions) | Done | +| CSRF + session security | Done | +| SSH key management | Done | +| OIDC / OAuth2 (optional) | Done | +| Access tokens (scoped, expiring) | Done | +| Deploy keys | Done | -- **Language:** Go (Golang) 1.21+ -- **Database:** PostgreSQL with XORM -- **Git Engine:** Native System Git Binary execution -- **CI/CD:** Forgejo Actions (gRPC protocol) +### Git Hosting +| Feature | Status | +|---------|--------| +| Smart HTTP transport (clone/push/pull) | Done | +| AGit protocol (`refs/for/` PR creation) | Done | +| Branch management | Done | +| Commit + diff viewing | Done | +| Git LFS (per-repo, configurable size limits) | Done | +| Branch protection rules | Done | -### Frontend & UX +### Collaboration +| Feature | Status | +|---------|--------| +| Pull requests (open/merged/closed) | Done | +| Issues | Done | +| Code review (inline comments, mobile bottom-sheet) | Done | +| Side-by-side + unified diff viewer | Done | +| Reviewer assignment | Done | +| Merge strategies (merge/squash/rebase) | Done | +| Webhooks | Done (model + routes) | +| Repository RBAC (read/write/admin) | Done | -- **Framework:** React 18+ (Embedded in Go binary) -- **Styling:** Tailwind CSS + Atlassian Design Tokens -- **Components:** Custom implementation of Atlaskit primitives -- **Real-time:** WebSockets for live logs and notifications +### CI/CD +| Feature | Status | +|---------|--------| +| Pipeline DAG visualization | In progress | +| CI orchestrator | Planned (Phase 2) | +| Runner manager | Planned (Phase 2) | +| Artifact registry | Planned (Phase 2) | +| Forgejo Actions integration (gRPC) | Planned (Phase 2) | +| Flaky test detection | Planned (Phase 2) | + +### GitOps + Environments +| Feature | Status | +|---------|--------| +| GitOps controller | Planned (Phase 3) | +| Environment management | Planned (Phase 3) | +| Drift detection | Planned (Phase 3) | +| Deployment promotion workflows | Planned (Phase 3) | +| Rollback visualization | Planned (Phase 3) | +| Canary / blue-green support | Planned (Phase 3) | + +### Observability + Security +| Feature | Status | +|---------|--------| +| Unified operational timeline | Planned (Phase 3) | +| Secret scanning | Planned (Phase 3) | +| Dependency scanning | Planned (Phase 3) | +| Signed artifacts (Sigstore/Cosign) | Planned (Phase 4) | +| Audit log | Planned (Phase 3) | + +### Federation +| Feature | Status | +|---------|--------| +| ActivityPub actor model | Done (data layer) | +| Federation handlers / inbox / outbox | Planned (Phase 3) | +| Cross-instance pull requests | Planned (Phase 3) | --- -## ✨ Key Features - -- **Responsive Navigation:** A triple-state sidebar (Expanded, Collapsed, Mobile Bottom-Bar) that adheres to an 8px grid system. -- **Advanced Diff Viewer:** Side-by-side and unified views with "Bottom Sheet" comment overlays for mobile code reviews. -- **Federated Pull Requests:** Interaction across different ForgeBucket/Forgejo instances via ActivityPub. -- **AGit "Quick Edit":** Web-based file editing with automatic `refs/for/` branch creation for instant PRs. -- **Skeleton Loading:** Optimized "Perceived Performance" using pulsate loading states for metadata. - ---- - -## 🔒 Security & Compliance - -- **OWASP Top 10 Compliance:** Strict protection against XSS, CSRF, and SQLi. -- **Command Sanitization:** Hardened wrapper for all Git binary executions. -- **Identity:** OIDC and OAuth2 support with Row-Level Security (RLS) mentalities. -- **Auditability:** Full logging of all administrative and git-over-HTTP actions. - ---- - -## 🏁 Getting Started - -### Prerequisites - -- Go 1.21 or higher -- Node.js 18+ (for frontend development) -- PostgreSQL 14+ -- System Git 2.20+ - -### Installation - -1. **Clone the repository:** +## Quick Start ```bash - git clone [https://github.com/your-repo/forgebucket.git](https://github.com/your-repo/forgebucket.git) - cd forgebucket +# 1. Clone and configure +git clone https://github.com/forgeo/forgebucket.git +cd forgebucket +cp .env.example .env # fill in SESSION_SECRET and CSRF_SECRET + +# 2. Start PostgreSQL +make docker-up + +# 3. Run DB migrations +make migrate + +# 4. Start both servers (Go :8080 + Vite :5173) +make dev ``` -2. **Setup Frontend:** +The Go API runs at `http://localhost:8080`. The Vite dev server runs at `http://localhost:5173` and proxies API requests. -```Bash -cd frontend -npm install -npm run build +--- + +## Architecture + +``` +ForgeBucket +├── API Gateway (Chi router, internal/api/) +├── Auth Service (sessions, CSRF, OIDC — internal/api/handlers/) +├── Repository Service (git HTTP, branches, LFS — internal/domain/git/) +├── Pull Request Service (PRs, reviews, merge — internal/api/handlers/) +├── Issue Service (issues, labels — internal/api/handlers/) +├── Federation Layer (ActivityPub actors — internal/domain/federation/) ← stub +├── CI Orchestrator (pipeline scheduling — internal/domain/ci/) ← stub +├── Secret Manager (env-based, scoped tokens — internal/config/) +├── Database (PostgreSQL + XORM — internal/models/) +└── Web Frontend (React 18 + TypeScript, embedded via //go:embed — web/) ``` -3. **Build the Binary:** - -```Bash -cd .. -go build -o forgebucket main.go +**Middleware chain (every request):** +``` +Logger → RealIP → Recoverer → CORS → CSRF → SessionAuth → RBAC → Handler ``` -4. **Run:** +--- -```Bash -./forgebucket web -``` +## Tech Stack -## 🤝 Contributing +| Layer | Technology | +|-------|------------| +| Language | Go 1.21+ | +| Router | Chi | +| ORM / Migrations | XORM + PostgreSQL | +| Frontend framework | React 18 + TypeScript | +| Build tool | Vite | +| Styling | Tailwind CSS v4 | +| Code editing | CodeMirror | +| Real-time | WebSockets | +| Container | Docker Compose (dev) | +| Federation | ActivityPub / ForgeFed | -We follow the "Responsive-First" contribution model. Please ensure all UI changes are tested on both Desktop (1440px) and Mobile (375px) breakpoints. +--- -## 📄 License +## Design System -This project is licensed under the MIT License - see the LICENSE file for details. Portions of the code are derived from Forgejo (GPLv3). \ No newline at end of file +ForgeBucket has its own design language — intentionally distinct from GitHub and GitLab. + +**Philosophy:** information-dense but calm. Inspired by Linear, Datadog, and VS Code — not enterprise CRUD forms. + +- **Colors:** Semantic token palette with full dark/light mode. Brand blue `#0052CC` (light) / `#3B82F6` (dark). Source of truth: `frontend/src/ui/tokens.ts` +- **Grid:** 8px base unit. All spacing is multiples of 4px (xs) or 8px (sm). No arbitrary pixel values. +- **Touch targets:** 44px minimum on all interactive elements (WCAG 2.5.5) +- **Navigation:** Triple-state sidebar (expanded 320px / collapsed 56px / mobile bottom bar). Keyboard-first. +- **Breakpoints:** Desktop 1440px, mobile 375px. Mobile code review uses bottom-sheet overlays, not modals. +- **Typography:** System font stack (Segoe UI, Roboto, sans-serif) + +--- + +## Environment Variables + +| Variable | Required | Description | +|----------|----------|-------------| +| `DATABASE_URL` | Yes | PostgreSQL connection string | +| `SESSION_SECRET` | Yes | Session signing key, ≥ 32 chars (`openssl rand -hex 32`) | +| `CSRF_SECRET` | Yes | CSRF key, exactly 32 chars (`openssl rand -hex 16`) | +| `PORT` | No | HTTP port, default `8080` | +| `REPO_ROOT` | Yes | Absolute path for bare git repository storage | +| `INSTANCE_URL` | Yes | Public URL of this instance (no trailing slash) | +| `INSTANCE_NAME` | No | Display name, default `ForgeBucket` | +| `OIDC_ISSUER` | No | OIDC provider URL | +| `OIDC_CLIENT_ID` | No | OIDC client ID | +| `OIDC_CLIENT_SECRET` | No | OIDC client secret | +| `DEBUG` | No | Disables Secure cookies, enables verbose logging | + +--- + +## Common Commands + +| Command | What it does | +|---------|-------------| +| `make dev` | Start Go API + Vite dev server concurrently | +| `make build` | Build frontend, embed into Go binary | +| `make migrate` | Sync XORM schemas to PostgreSQL | +| `make test` | Run Go tests + Vitest | +| `make lint` | `go vet` + ESLint | +| `make docker-up` | Start PostgreSQL via Docker Compose | + +--- + +## Roadmap + +| Phase | Focus | Status | +|-------|-------|--------| +| Phase 1 | Core Git hosting, auth, PRs, issues, RBAC, design system | Done | +| Phase 2 | CI/CD orchestrator, runner manager, pipeline visualization, artifact registry | In progress | +| Phase 3 | GitOps controller, environments, observability, federation handlers, audit log | Planned | +| Phase 4 | Command palette, AI diagnostics, signed artifacts, package registry | Planned | + +--- + +## Contributing + +See [AGENTS.md](AGENTS.md) for AI-assisted development conventions, architecture boundaries, and what not to build without discussion. + +All UI contributions must be tested at both 1440px desktop and 375px mobile. Spacing must use tokens from `frontend/src/ui/tokens.ts` — no arbitrary pixel values. + +--- + +## Module Path + +`github.com/forgeo/forgebucket` + +--- + +## License + +MIT License. See LICENSE for details. diff --git a/ai_agent_master_prompt_for_building_modern_git_platform.md b/ai_agent_master_prompt_for_building_modern_git_platform.md new file mode 100644 index 0000000..7b5050d --- /dev/null +++ b/ai_agent_master_prompt_for_building_modern_git_platform.md @@ -0,0 +1,741 @@ +# MASTER IMPLEMENTATION PROMPT +## Building a Modern Git Platform with CI/CD + GitOps + Operational UX + +You are an elite senior staff engineer, platform architect, DevOps architect, distributed systems engineer, and product UX engineer. + +You are tasked with designing and implementing a next-generation self-hosted Git platform. + +This platform exists in the category of: +- GitHub +- GitLab +- Forgejo +- Gitea +- Bitbucket + +BUT: + +You must NOT merely clone existing platforms. + +The goal is to create: + +> a modern developer operations platform + +that deeply integrates: +- Git hosting +- pull requests +- CI/CD +- GitOps +- deployments +- environments +- observability +- security +- operational awareness +- developer productivity + +The platform should feel: +- fast +- operational +- developer-first +- low cognitive load +- modern +- reliable +- modular +- keyboard-first +- context-aware + +The product philosophy is: + +> repositories are operational systems + +NOT: + +> collections of files. + +================================================== +HIGH LEVEL PRODUCT GOALS +================================================== + +The platform should optimize for: + +- immediate situational awareness +- workflow continuity +- deployment visibility +- operational clarity +- reliability +- developer flow +- observability +- intelligent automation +- security by default +- excellent UX + +Users should always be able to answer: + +- what changed? +- what failed? +- what deployed? +- what is unhealthy? +- what needs my attention? +- what environments are affected? +- what should I review next? +- what caused this incident? + +without navigating deeply. + +================================================== +CORE PRODUCT PRINCIPLES +================================================== + +1. UX FIRST + +Most Git platforms prioritize functionality over usability. + +This platform must prioritize: +- readability +- discoverability +- contextual awareness +- progressive disclosure +- speed +- low noise +- operational understanding + +Avoid: +- tab overload +- enterprise clutter +- giant forms +- notification spam +- YAML-centric UX +- log-centric UX + +The system should feel: +- intentional +- calm +- efficient +- operationally intelligent + +-------------------------------------------------- + +2. OPERATIONAL AWARENESS + +The platform must continuously surface: +- failing pipelines +- deployment health +- environment drift +- flaky tests +- security issues +- review bottlenecks +- dependency risks +- deployment risks + +This information should appear naturally throughout the UI. + +-------------------------------------------------- + +3. REPOSITORIES ARE RUNTIME SYSTEMS + +The repository page should not simply display files. + +It should display: +- deployments +- environments +- active PRs +- operational health +- timelines +- incidents +- ownership +- risk +- observability + +The file tree is secondary. + +-------------------------------------------------- + +4. GITOPS IS FIRST CLASS + +Git should become: +- source of truth +- deployment history +- environment state definition +- rollback system +- audit log + +The system must support: +- reconciliation +- drift detection +- declarative environments +- promotion workflows +- rollback visualization +- environment topology + +-------------------------------------------------- + +5. RELIABILITY IS A PRIMARY FEATURE + +The platform should optimize for: +- deterministic execution +- idempotency +- isolation +- resilience +- queue durability +- observability +- safe rollbacks +- fault tolerance + +================================================== +ARCHITECTURE REQUIREMENTS +================================================== + +Design the platform using modular services. + +Suggested architecture: + +```txt +Platform +├── API Gateway +├── Auth Service +├── Repository Service +├── Pull Request Service +├── Issue Service +├── Event Bus +├── CI Orchestrator +├── Runner Manager +├── Artifact Registry +├── Package Registry +├── Deployment Engine +├── GitOps Controller +├── Environment Service +├── Secret Manager +├── Notification Service +├── Search Service +├── Observability Layer +├── Metrics Service +├── Audit Service +└── Web Frontend +``` + +================================================== +EVENT DRIVEN ARCHITECTURE +================================================== + +The platform should be event-driven. + +Everything emits events. + +Examples: + +```txt +repo.created +push.created +pr.opened +review.requested +pipeline.started +pipeline.failed +artifact.published +deployment.started +deployment.failed +environment.drift_detected +incident.created +``` + +Requirements: +- durable events +- replay support +- auditability +- timeline reconstruction +- reactive UI updates + +Recommended technologies: +- NATS +- Kafka +- RabbitMQ + +Prefer NATS initially for simplicity. + +================================================== +CI/CD SYSTEM REQUIREMENTS +================================================== + +The CI/CD system must support: + +- DAG pipelines +- matrix builds +- reusable workflows +- workflow templates +- conditional execution +- parallel execution +- artifacts +- caches +- retries +- concurrency controls +- cancellation +- pipeline graphs +- environment promotion +- rollback support +- preview environments +- flaky test detection +- deployment visualization + +The orchestrator should: +- schedule +- coordinate +- monitor + +NOT directly execute jobs. + +================================================== +RUNNER SYSTEM REQUIREMENTS +================================================== + +Runners should: +- be ephemeral +- isolated +- disposable +- reproducible +- stateless + +Support execution backends: + +1. Docker containers +2. Kubernetes jobs +3. Firecracker microVMs +4. Bare metal runners + +Security is critical. + +Forked PRs must never automatically receive secrets. + +================================================== +SECRET MANAGEMENT +================================================== + +Implement scoped secret management. + +Secret hierarchy: + +```txt +Global +→ Organization +→ Repository +→ Environment +→ Runtime ephemeral injection +``` + +Support: +- Vault +- OIDC federation +- cloud secret providers +- encrypted secret storage + +Secrets must: +- never leak to logs +- be masked automatically +- support audit trails +- support rotation + +================================================== +ARTIFACT + PACKAGE MANAGEMENT +================================================== + +Implement: +- build artifact storage +- OCI registry +- package registries +- retention policies +- artifact provenance +- signing support +- SBOM support + +Support: +- container images +- npm +- cargo +- pip +- maven +- generic artifacts + +================================================== +GITOPS REQUIREMENTS +================================================== + +GitOps must be deeply integrated. + +Support: +- reconciliation loops +- drift detection +- sync visualization +- environment topology +- deployment promotion +- rollback flows +- canary releases +- blue/green deployments +- environment history + +The UI should make GitOps understandable. + +Avoid overwhelming Kubernetes-centric UX. + +================================================== +DATABASE + STORAGE DESIGN +================================================== + +Separate: +- application code +- repository storage +- artifacts +- caches +- logs +- uploads + +Repository storage should NOT exist in the app repository. + +Recommended: + +```txt +/data/repos +/data/artifacts +/data/cache +/data/uploads +``` + +Repository storage is runtime instance data. + +Treat it like: +- database files +- object storage +- runtime state + +================================================== +DASHBOARD REQUIREMENTS +================================================== + +The dashboard should behave like: + +> an operational command center + +NOT: + +> a repository list. + +Include: + +1. Attention Required +- failing pipelines +- stale PRs +- security alerts +- deployment failures +- environment drift + +2. Active Workspaces +- active repos +- active branches +- assigned reviews +- recent deployments + +3. Team Activity +- merges +- releases +- deployments +- incidents + +4. CI/CD Overview +- pipeline health +- queue health +- flaky tests +- deployment status + +5. Review Dashboard +- pending reviews +- high risk PRs +- stale reviews + +6. Security Overview +- dependency vulnerabilities +- secret leaks +- suspicious pushes + +================================================== +REPOSITORY PAGE REQUIREMENTS +================================================== + +The repository page must feel operational. + +Top area should include: + +```txt +Repo Name +Production: Healthy +CI: Passing +Deployments: 3 active +Risk: Medium +``` + +The page should include: + +- active PRs +- deployments +- environments +- repository health +- security alerts +- ownership +- recent activity +- operational timeline +- preview environments +- CI/CD overview +- deployment history + +The README should not dominate the page. + +================================================== +UNIFIED OPERATIONAL TIMELINE +================================================== + +Implement a unified timeline merging: +- commits +- deployments +- incidents +- rollbacks +- CI failures +- security events +- alerts +- releases + +This is one of the most important features. + +Users should easily answer: + +> what changed before things broke? + +================================================== +PIPELINE UX REQUIREMENTS +================================================== + +Pipelines should be visual DAGs. + +Support: +- dependency visualization +- execution timing +- bottleneck detection +- retry controls +- artifact visibility +- live execution state +- grouped logs +- semantic errors + +Logs should support: +- filtering +- collapsing +- syntax highlighting +- structured parsing +- AI summarization + +================================================== +DEPLOYMENT UX REQUIREMENTS +================================================== + +Deployments must feel first-class. + +Each environment should expose: + +```txt +Production +Healthy +v1.4.2 +3 pods +0.1% errors +Last deploy 14m ago +``` + +Support: +- rollback +- traffic shifting +- canary visibility +- deployment timelines +- release notes +- environment logs +- health checks + +================================================== +COMMAND PALETTE REQUIREMENTS +================================================== + +Implement a global command palette. + +Inspired by: +- VS Code +- Raycast +- Linear + +Examples: + +```txt +/retry failed jobs +/deploy staging +/open logs +/review next +/show flaky tests +/open production incidents +``` + +Keyboard-first navigation is critical. + +================================================== +AI-ASSISTED FEATURES +================================================== + +Implement optional AI-assisted operational tooling. + +Examples: + +- failure diagnosis +- flaky test detection +- architecture summaries +- impact analysis +- deployment risk scoring +- review summaries +- onboarding explanations + +Example: + +```txt +Likely failure cause: +Database migration introduced lock contention. +``` + +================================================== +OBSERVABILITY REQUIREMENTS +================================================== + +Integrate: +- metrics +- traces +- logs +- deployment state +- incident state +- service topology + +Do not isolate observability into external systems. + +Expose operational health directly in repository pages. + +================================================== +RELIABILITY REQUIREMENTS +================================================== + +Implement: +- durable queues +- retries +- dead-letter queues +- resumable pipelines +- distributed scheduling +- concurrency controls +- checkpointing +- idempotent operations + +The platform should survive: +- runner crashes +- orchestrator crashes +- network partitions +- deployment interruptions + +================================================== +SECURITY REQUIREMENTS +================================================== + +Implement: +- signed artifacts +- provenance verification +- branch protections +- permission scopes +- audit logging +- secret scanning +- dependency scanning +- runner isolation +- sandboxing + +Support: +- Sigstore +- Cosign +- SLSA concepts + +================================================== +UI/UX DESIGN LANGUAGE +================================================== + +The UI should feel: +- modern +- minimal +- operational +- clean +- responsive +- keyboard-first +- information dense but calm + +Visual inspirations: +- Linear +- Datadog +- Grafana +- Raycast +- Arc Browser +- VS Code +- modern observability dashboards + +Avoid: +- clutter +- giant tables +- excessive modal workflows +- deeply nested navigation + +================================================== +IMPLEMENTATION EXPECTATIONS +================================================== + +You should: +- think deeply about architecture +- optimize for maintainability +- optimize for extensibility +- prioritize UX heavily +- prioritize reliability heavily +- explain tradeoffs +- avoid overengineering early +- support future scalability + +You should continuously ask: + +- does this reduce cognitive load? +- does this improve operational awareness? +- does this improve developer flow? +- does this improve reliability? +- does this make debugging easier? + +================================================== +DELIVERABLES +================================================== + +When implementing features: + +Provide: +- architecture reasoning +- schema design +- API design +- event definitions +- service boundaries +- UI mockups +- workflow diagrams +- UX rationale +- security implications +- scaling considerations +- operational implications + +Always optimize for: +- clarity +- reliability +- developer experience +- operational intelligence +- future extensibility + +The platform should ultimately feel like: + +> a unified operating system for software delivery + +rather than: + +> a Git repository viewer with CI attached.