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