diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 000000000..9c05aca53
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,379 @@
+# Architecture Documentation
+
+## System Architecture
+
+Release Controller is a Kubernetes-native system that uses Custom Resources (ReleasePayloads) and ImageStreams to manage OpenShift releases. The architecture follows a controller pattern where multiple controllers work together to orchestrate the release process.
+
+### High-Level Architecture Diagram
+
+```mermaid
+graph TB
+ subgraph "Input Sources"
+ ART[ART ImageStreams
ocp/4.15-art-latest]
+ CI[CI Builds]
+ end
+
+ subgraph "Release Controller System"
+ RC[Release Controller
Core Orchestrator]
+ API[Release Controller API
Web UI & REST API]
+ RPC[Release Payload Controller
CRD Manager]
+ RRC[Release Reimport Controller
Reimport Handler]
+ end
+
+ subgraph "Kubernetes Cluster"
+ IS[ImageStreams
Source & Release]
+ RP[ReleasePayloads
CRs]
+ JOBS[Kubernetes Jobs
Release Creation]
+ PJ[ProwJobs
Verification Tests]
+ end
+
+ subgraph "Output"
+ REGISTRY[Container Registry
Published Releases]
+ WEB[Web Interface
Release Information]
+ JIRA[Jira
Issue Tracking]
+ end
+
+ ART -->|Updates| IS
+ CI -->|Creates| IS
+ RC -->|Monitors| IS
+ RC -->|Creates| RP
+ RC -->|Launches| JOBS
+ RC -->|Creates| PJ
+ RC -->|Mirrors| IS
+
+ RPC -->|Manages| RP
+ RPC -->|Monitors| PJ
+ RPC -->|Updates| RP
+
+ RRC -->|Reimports| IS
+
+ API -->|Reads| IS
+ API -->|Reads| RP
+ API -->|Serves| WEB
+
+ JOBS -->|Publishes| REGISTRY
+ RC -->|Updates| JIRA
+
+ style RC fill:#e1f5ff
+ style RPC fill:#fff4e1
+ style API fill:#e8f5e9
+```
+
+## Component Architecture
+
+### Release Creation Flow
+
+```mermaid
+sequenceDiagram
+ participant ART as ART ImageStream
+ participant RC as Release Controller
+ participant RP as ReleasePayload
+ participant Job as Creation Job
+ participant Registry as Container Registry
+ participant PJ as ProwJobs
+
+ ART->>RC: ImageStream Updated
+ RC->>RC: Check Release Config
+ RC->>RP: Create ReleasePayload
+ RC->>Job: Launch Creation Job
+ Job->>Job: Assemble Release
+ Job->>Registry: Push Release Image
+ Job->>RC: Update Status
+ RC->>PJ: Launch Verification Jobs
+ PJ->>RC: Report Results
+ RC->>RP: Update Payload Status
+```
+
+### Release Verification Flow
+
+```mermaid
+graph TD
+ A[Release Created] --> B[ReleasePayload Created]
+ B --> C[Verification Jobs Launched]
+ C --> D{All Jobs Pass?}
+ D -->|Yes| E[Payload Accepted]
+ D -->|No| F[Payload Rejected]
+ E --> G[Release Published]
+ F --> H[Release Blocked]
+
+ style E fill:#e8f5e9
+ style F fill:#ffebee
+```
+
+### Data Flow Diagram
+
+```mermaid
+flowchart TD
+ subgraph "Input Sources"
+ ARTStreams[ART ImageStreams]
+ CIBuilds[CI Build Outputs]
+ Config[Release Configs]
+ end
+
+ subgraph "Processing"
+ RC[Release Controller]
+ RPC[Release Payload Controller]
+ RRC[Release Reimport Controller]
+ end
+
+ subgraph "Storage"
+ ImageStreams[ImageStreams]
+ ReleasePayloads[ReleasePayloads]
+ GCS[GCS Artifacts]
+ Audit[Audit Logs]
+ end
+
+ subgraph "Output"
+ Registry[Container Registry]
+ WebUI[Web Interface]
+ Jira[Jira Issues]
+ end
+
+ ARTStreams --> RC
+ CIBuilds --> RC
+ Config --> RC
+
+ RC --> ImageStreams
+ RC --> ReleasePayloads
+ RC --> GCS
+ RC --> Audit
+
+ RPC --> ReleasePayloads
+ RRC --> ImageStreams
+
+ ImageStreams --> Registry
+ ReleasePayloads --> WebUI
+ RC --> Jira
+
+ style RC fill:#e1f5ff
+ style RPC fill:#fff4e1
+```
+
+## Deployment Architecture
+
+### Production Deployment
+
+```mermaid
+graph TB
+ subgraph "Release Controller Namespace"
+ RCPod[Release Controller Pod]
+ APIPod[API Server Pod]
+ RPCPod[Release Payload Controller Pod]
+ RRCPod[Reimport Controller Pod]
+ end
+
+ subgraph "Kubernetes Cluster"
+ ImageStreams[ImageStreams]
+ ReleasePayloads[ReleasePayloads]
+ Jobs[Kubernetes Jobs]
+ ProwJobs[ProwJobs]
+ end
+
+ subgraph "External Services"
+ Registry[Container Registry]
+ GCS[Google Cloud Storage]
+ Jira[Jira]
+ Prow[Prow CI]
+ end
+
+ RCPod --> ImageStreams
+ RCPod --> ReleasePayloads
+ RCPod --> Jobs
+ RCPod --> ProwJobs
+
+ RPCPod --> ReleasePayloads
+ RRCPod --> ImageStreams
+
+ APIPod --> ImageStreams
+ APIPod --> ReleasePayloads
+
+ Jobs --> Registry
+ RCPod --> GCS
+ RCPod --> Jira
+ ProwJobs --> Prow
+
+ style RCPod fill:#e1f5ff
+ style RPCPod fill:#fff4e1
+```
+
+### Controller Architecture
+
+The release-payload-controller runs multiple sub-controllers:
+
+```mermaid
+graph LR
+ subgraph "release-payload-controller"
+ PCC[Payload Creation Controller]
+ PMC[Payload Mirror Controller]
+ PJC[ProwJob Controller]
+ PAC[Payload Accepted Controller]
+ PRC[Payload Rejected Controller]
+ PVC[Payload Verification Controller]
+ end
+
+ subgraph "Kubernetes API"
+ RP[ReleasePayloads]
+ Jobs[Jobs]
+ PJ[ProwJobs]
+ end
+
+ PCC --> RP
+ PCC --> Jobs
+ PMC --> RP
+ PMC --> Jobs
+ PJC --> PJ
+ PJC --> RP
+ PAC --> RP
+ PRC --> RP
+ PVC --> RP
+
+ style PCC fill:#e1f5ff
+ style PJC fill:#fff4e1
+```
+
+## Component Interaction Diagram
+
+```mermaid
+graph TB
+ subgraph "Monitoring Layer"
+ RC[Release Controller]
+ end
+
+ subgraph "Management Layer"
+ RPC[Release Payload Controller]
+ RRC[Release Reimport Controller]
+ end
+
+ subgraph "Presentation Layer"
+ API[Release Controller API]
+ end
+
+ subgraph "Integration Layer"
+ Jira[Jira Integration]
+ Signer[Release Signer]
+ Audit[Audit Backend]
+ end
+
+ RC --> RPC
+ RC --> RRC
+ RC --> API
+ RC --> Jira
+ RC --> Signer
+ RC --> Audit
+
+ RPC --> RC
+ API --> RC
+
+ style RC fill:#e1f5ff
+ style RPC fill:#fff4e1
+```
+
+## Key Design Patterns
+
+### 1. Controller Pattern
+All components follow the Kubernetes controller pattern:
+- Watch for resource changes
+- Reconcile desired state
+- Handle errors and retries gracefully
+- Update resource status
+
+### 2. Custom Resources
+ReleasePayload CRD represents release state:
+- Tracks release creation progress
+- Manages verification status
+- Handles acceptance/rejection
+- Stores release metadata
+
+### 3. ImageStream-Based
+Uses OpenShift ImageStreams for:
+- Source image tracking
+- Release image creation
+- Image mirroring
+- Point-in-time snapshots
+
+### 4. Job-Based Execution
+Release operations execute as Kubernetes Jobs:
+- Release creation jobs
+- Mirror jobs
+- Verification jobs
+- Independent and retryable
+
+### 5. Event-Driven
+System responds to events:
+- ImageStream updates trigger releases
+- Job completions trigger status updates
+- ReleasePayload changes trigger actions
+
+## Security Architecture
+
+```mermaid
+graph TB
+ subgraph "Authentication"
+ ServiceAccounts[K8s Service Accounts]
+ RegistryAuth[Registry Authentication]
+ end
+
+ subgraph "Authorization"
+ RBAC[Kubernetes RBAC]
+ ImageStreamPermissions[ImageStream Permissions]
+ end
+
+ subgraph "Security Features"
+ Signing[Release Signing]
+ Audit[Audit Logging]
+ Verification[Release Verification]
+ end
+
+ ServiceAccounts --> RBAC
+ RegistryAuth --> ImageStreamPermissions
+
+ RBAC --> Signing
+ ImageStreamPermissions --> Audit
+ Signing --> Verification
+
+ style Signing fill:#e1f5ff
+ style Audit fill:#fff4e1
+```
+
+## Scalability Considerations
+
+1. **Horizontal Scaling**: Controllers can be scaled horizontally
+2. **Job Parallelization**: Multiple release jobs can run concurrently
+3. **Caching**: ImageStream informers cache resource state
+4. **Resource Management**: Garbage collection manages old releases
+5. **Efficient API Usage**: Informers and watches for Kubernetes API
+
+## Monitoring and Observability
+
+```mermaid
+graph LR
+ subgraph "Metrics Collection"
+ Prometheus[Prometheus]
+ Metrics[Metrics Endpoints]
+ end
+
+ subgraph "Logging"
+ K8sLogs[Kubernetes Logs]
+ AuditLogs[Audit Logs]
+ end
+
+ subgraph "Tracing"
+ OpenTelemetry[OpenTelemetry]
+ end
+
+ subgraph "Dashboards"
+ Grafana[Grafana]
+ WebUI[Web UI]
+ end
+
+ Prometheus --> Grafana
+ Metrics --> Prometheus
+ K8sLogs --> Grafana
+ AuditLogs --> Grafana
+ OpenTelemetry --> Grafana
+ WebUI --> Metrics
+
+ style Prometheus fill:#e1f5ff
+ style Grafana fill:#fff4e1
+```
+
diff --git a/docs/ARCHITECTURE_DIAGRAMS.md b/docs/ARCHITECTURE_DIAGRAMS.md
new file mode 100644
index 000000000..3f3308387
--- /dev/null
+++ b/docs/ARCHITECTURE_DIAGRAMS.md
@@ -0,0 +1,605 @@
+# Release Controller Architecture Diagrams
+
+This document contains two architecture diagrams:
+
+1. **Basic Overview**: High-level view of the system components
+2. **Complete Architecture**: Detailed view of all components and their interactions
+
+> **Note**: These diagrams use Mermaid syntax. If your viewer doesn't support Mermaid, see the ASCII alternatives below.
+
+## Diagram 1: Basic Overview
+
+This diagram provides a high-level overview of the release-controller system and its main components.
+
+```mermaid
+graph TB
+ subgraph "Input"
+ ART[ART ImageStream
ocp/4.15-art-latest]
+ end
+
+ subgraph "Release Controller System"
+ RC[Release Controller
Core Orchestrator]
+ API[Release Controller API
Web UI & REST API]
+ RPC[Release Payload Controller
CRD Manager]
+ RRC[Release Reimport Controller
Reimport Handler]
+ end
+
+ subgraph "Kubernetes Cluster"
+ IS[ImageStreams
Source & Release]
+ JOBS[Kubernetes Jobs
Release Creation]
+ PJ[ProwJobs
Verification Tests]
+ RP[ReleasePayloads
CRs]
+ end
+
+ subgraph "Output"
+ REGISTRY[Container Registry
Published Releases]
+ WEB[Web Interface
Release Information]
+ end
+
+ ART -->|Creates/Updates| IS
+ RC -->|Monitors| IS
+ RC -->|Creates| RP
+ RC -->|Launches| JOBS
+ RC -->|Creates| PJ
+
+ RPC -->|Manages| RP
+ RPC -->|Monitors| PJ
+
+ API -->|Reads| IS
+ API -->|Reads| RP
+ API -->|Serves| WEB
+
+ JOBS -->|Creates| IS
+ PJ -->|Updates| RP
+
+ RC -->|Publishes| REGISTRY
+
+ style RC fill:#e1f5ff
+ style API fill:#fff4e1
+ style RPC fill:#e8f5e9
+ style RRC fill:#fce4ec
+```
+
+### ASCII Alternative (Basic Overview)
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│ INPUT │
+│ ART ImageStream (ocp/4.15-art-latest) │
+└────────────────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ RELEASE CONTROLLER SYSTEM │
+│ │
+│ ┌──────────────────┐ ┌──────────────────┐ │
+│ │ Release │ │ Release │ │
+│ │ Controller │ │ Controller API │ │
+│ │ (Core) │ │ (Web UI) │ │
+│ └────────┬─────────┘ └────────┬─────────┘ │
+│ │ │ │
+│ ┌────────▼─────────┐ ┌─────────▼─────────┐ │
+│ │ Release Payload │ │ Release Reimport │ │
+│ │ Controller │ │ Controller │ │
+│ │ (CR Manager) │ │ (Reimport) │ │
+│ └──────────────────┘ └──────────────────┘ │
+└────────────────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ KUBERNETES CLUSTER │
+│ │
+│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
+│ │ ImageStreams │ │ Jobs │ │ ProwJobs │ │
+│ │ │ │ │ │ │ │
+│ └──────────────┘ └──────────────┘ └──────────────┘ │
+│ │
+│ ┌──────────────┐ │
+│ │ Release │ │
+│ │ Payloads │ │
+│ │ (CRDs) │ │
+│ └──────────────┘ │
+└────────────────────────────┬────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ OUTPUT │
+│ │
+│ ┌──────────────┐ ┌──────────────┐ │
+│ │ Container │ │ Web │ │
+│ │ Registry │ │ Interface │ │
+│ └──────────────┘ └──────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Diagram 2: Complete Architecture - Controller and Components
+
+This detailed diagram shows all components, their interactions, and the complete flow of release processing.
+
+```mermaid
+graph TB
+ subgraph "External Systems"
+ ART[ART Pipeline
Updates ImageStreams]
+ JIRA[Jira
Issue Tracking]
+ GITHUB[GitHub
PR Information]
+ PROW[Prow
Test Infrastructure]
+ end
+
+ subgraph "Release Controller Main"
+ direction TB
+ subgraph "Event Handlers"
+ ISH[ImageStream Handler]
+ JH[Job Handler]
+ PJH[ProwJob Handler]
+ RPH[ReleasePayload Handler]
+ end
+
+ subgraph "Work Queues"
+ MAINQ[Main Queue
Release Sync]
+ GCQ[GC Queue
Garbage Collection]
+ AUDITQ[Audit Queue
Release Auditing]
+ JIRAQ[Jira Queue
Issue Updates]
+ LEGACYQ[Legacy Queue
Migration]
+ end
+
+ subgraph "Core Sync Functions"
+ SYNC[sync
Main Release Logic]
+ SYNCREL[syncRelease
Create Release Tags]
+ SYNCMIR[syncMirror
Image Mirroring]
+ SYNCVER[syncVerify
Verification Jobs]
+ SYNCGC[syncGC
Garbage Collection]
+ SYNCAUDIT[syncAudit
Release Auditing]
+ SYNCJIRA[syncJira
Jira Updates]
+ end
+
+ subgraph "Supporting Components"
+ RELEASEINFO[ReleaseInfo
Release Metadata]
+ GRAPH[UpgradeGraph
Upgrade Paths]
+ SIGNER[Signer
Release Signing]
+ CACHE[ImageCache
Latest Images]
+ end
+ end
+
+ subgraph "Release Controller API"
+ direction TB
+ HTTP[HTTP Server
Port 8080]
+ UI[Web UI Handler]
+ REST[REST API Handlers]
+ CANDIDATE[Candidate Handler]
+ CHANGELOG[Changelog Handler]
+ COMPARE[Compare Handler]
+ GRAPHVIS[Graph Visualization]
+ end
+
+ subgraph "Release Payload Controller"
+ direction TB
+ subgraph "Payload Controllers"
+ PCREATE[Payload Creation
Controller]
+ PVERIFY[Payload Verification
Controller]
+ PACCEPT[Payload Accepted
Controller]
+ PREJECT[Payload Rejected
Controller]
+ PMIRROR[Payload Mirror
Controller]
+ end
+
+ subgraph "Job Controllers"
+ JOBSTATE[Job State
Controller]
+ LEGACYJOB[Legacy Job Status
Controller]
+ RELEASECREATE[Release Creation Job
Controller]
+ RELEASEMIRROR[Release Mirror Job
Controller]
+ end
+ end
+
+ subgraph "Kubernetes Resources"
+ direction TB
+ subgraph "ImageStreams"
+ SOURCEIS[Source ImageStream
ocp/4.15-art-latest]
+ RELEASEIS[Release ImageStream
ocp/4.15]
+ MIRRORIS[Mirror ImageStream
ocp/4.15-mirror-xxx]
+ end
+
+ subgraph "Jobs"
+ RELEASEJOB[Release Creation Job
oc adm release new]
+ ANALYSISJOB[Analysis Job]
+ AGGREGATIONJOB[Aggregation Job]
+ end
+
+ subgraph "ProwJobs"
+ BLOCKINGPJ[Blocking
Verification Jobs]
+ INFORMINGPJ[Informing
Verification Jobs]
+ UPGRADEPJ[Upgrade
Test Jobs]
+ end
+
+ subgraph "CRs"
+ RELEASEPAYLOAD[ReleasePayload
Custom Resource]
+ end
+ end
+
+ subgraph "Storage & Output"
+ GCS[GCS Bucket
Audit Logs]
+ REGISTRY[Container Registry
Published Releases]
+ SECRETS[Kubernetes Secrets
Upgrade Graph]
+ end
+
+ %% External to Controller
+ ART -->|Updates| SOURCEIS
+ SOURCEIS -->|Informer Event| ISH
+ ISH -->|Enqueue| MAINQ
+
+ %% Main Controller Flow
+ MAINQ -->|Process| SYNC
+ SYNC -->|Calls| SYNCREL
+ SYNC -->|Calls| SYNCMIR
+ SYNC -->|Calls| SYNCVER
+ SYNC -->|Calls| SYNCGC
+
+ SYNCREL -->|Creates| RELEASEIS
+ SYNCREL -->|Creates Tag| RELEASEIS
+ SYNCREL -->|Launches| RELEASEJOB
+
+ SYNCMIR -->|Creates| MIRRORIS
+ SYNCMIR -->|Mirrors Images| MIRRORIS
+
+ SYNCVER -->|Reads Prow Config| PROW
+ SYNCVER -->|Creates| BLOCKINGPJ
+ SYNCVER -->|Creates| INFORMINGPJ
+ SYNCVER -->|Creates| UPGRADEPJ
+
+ RELEASEJOB -->|Completes| JH
+ JH -->|Enqueue| MAINQ
+
+ BLOCKINGPJ -->|Status Update| PJH
+ PJH -->|Enqueue| MAINQ
+
+ %% Release Payload Flow
+ SYNCREL -->|Creates| RELEASEPAYLOAD
+ RELEASEPAYLOAD -->|Informer Event| PCREATE
+ PCREATE -->|Updates Conditions| RELEASEPAYLOAD
+
+ BLOCKINGPJ -->|Status| PVERIFY
+ INFORMINGPJ -->|Status| PVERIFY
+ UPGRADEPJ -->|Status| PVERIFY
+ PVERIFY -->|Updates| RELEASEPAYLOAD
+
+ RELEASEPAYLOAD -->|Accepted| PACCEPT
+ RELEASEPAYLOAD -->|Rejected| PREJECT
+
+ RELEASEJOB -->|Status| RELEASECREATE
+ RELEASECREATE -->|Updates| RELEASEPAYLOAD
+
+ %% API Flow
+ HTTP -->|Routes| UI
+ HTTP -->|Routes| REST
+ REST -->|Reads| SOURCEIS
+ REST -->|Reads| RELEASEIS
+ REST -->|Reads| RELEASEPAYLOAD
+ REST -->|Calls| CANDIDATE
+ REST -->|Calls| CHANGELOG
+ REST -->|Calls| COMPARE
+ REST -->|Calls| GRAPHVIS
+
+ CHANGELOG -->|Uses| RELEASEINFO
+ COMPARE -->|Uses| RELEASEINFO
+ GRAPHVIS -->|Reads| GRAPH
+
+ %% Supporting Components
+ SYNC -->|Uses| RELEASEINFO
+ RELEASEINFO -->|Executes| RELEASEJOB
+ RELEASEINFO -->|Caches| CACHE
+ CACHE -->|Gets Latest| SOURCEIS
+
+ SYNC -->|Updates| GRAPH
+ UPGRADEPJ -->|Results| GRAPH
+ GRAPH -->|Stored In| SECRETS
+
+ %% Audit Flow
+ RELEASEIS -->|Tag Ready| AUDITQ
+ AUDITQ -->|Process| SYNCAUDIT
+ SYNCAUDIT -->|Launches| ANALYSISJOB
+ SYNCAUDIT -->|Uses| SIGNER
+ SYNCAUDIT -->|Writes| GCS
+
+ %% Jira Flow
+ RELEASEIS -->|Accepted| JIRAQ
+ JIRAQ -->|Process| SYNCJIRA
+ SYNCJIRA -->|Reads| GITHUB
+ SYNCJIRA -->|Updates| JIRA
+
+ %% Legacy Migration
+ RELEASEIS -->|Old Tags| LEGACYQ
+ LEGACYQ -->|Migrates| RELEASEPAYLOAD
+
+ %% Garbage Collection
+ GCQ -->|Process| SYNCGC
+ SYNCGC -->|Deletes Old| RELEASEIS
+ SYNCGC -->|Deletes Old| MIRRORIS
+
+ %% Publishing
+ PACCEPT -->|Publishes| REGISTRY
+
+ style RC fill:#e1f5ff
+ style API fill:#fff4e1
+ style RPC fill:#e8f5e9
+ style SYNC fill:#bbdefb
+ style RELEASEPAYLOAD fill:#c8e6c9
+ style PROW fill:#fff9c4
+```
+
+### ASCII Alternative (Complete Architecture - Simplified)
+
+```text
+┌─────────────────────────────────────────────────────────────────────┐
+│ EXTERNAL SYSTEMS │
+│ ART Pipeline │ Jira │ GitHub │ Prow │
+└────────┬───────┴─────────┴──────────┴───────────┬───────────────────┘
+ │ │
+ │ Updates ImageStream │ Executes Tests
+ ▼ │
+┌─────────────────────────────────────────────────┴───────────────────┐
+│ RELEASE CONTROLLER MAIN │
+│ │
+│ ┌──────────────────────────────────────────────────────────────┐ │
+│ │ EVENT HANDLERS │ │
+│ │ ImageStream │ Job │ ProwJob │ ReleasePayload │ │
+│ └──────────────┬────────────────────────────────────────────────┘ │
+│ │ │
+│ ┌──────────────▼────────────────────────────────────────────────┐ │
+│ │ WORK QUEUES │ │
+│ │ Main │ GC │ Audit │ Jira │ Legacy │ │
+│ └──────────────┬────────────────────────────────────────────────┘ │
+│ │ │
+│ ┌──────────────▼────────────────────────────────────────────────┐ │
+│ │ CORE SYNC FUNCTIONS │ │
+│ │ sync │ syncRelease │ syncMirror │ syncVerify │ syncGC │ │
+│ └──────────────┬────────────────────────────────────────────────┘ │
+│ │ │
+│ ┌──────────────▼────────────────────────────────────────────────┐ │
+│ │ SUPPORTING COMPONENTS │ │
+│ │ ReleaseInfo │ UpgradeGraph │ Signer │ ImageCache │ │
+│ └──────────────────────────────────────────────────────────────┘ │
+└────────────────────────────┬────────────────────────────────────────┘
+ │
+ ┌───────────────────┴───────────────────┐
+ │ │
+ ▼ ▼
+┌──────────────────────┐ ┌──────────────────────┐
+│ RELEASE CONTROLLER │ │ RELEASE PAYLOAD │
+│ API │ │ CONTROLLER │
+│ │ │ │
+│ HTTP Server │ │ Payload Controllers │
+│ Web UI │ │ Job Controllers │
+│ REST API │ │ │
+└──────────────────────┘ └──────────────────────┘
+ │ │
+ └───────────────────┬───────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ KUBERNETES RESOURCES │
+│ │
+│ ImageStreams: Source │ Release │ Mirror │
+│ Jobs: Release Creation │ Analysis │ Aggregation │
+│ ProwJobs: Blocking │ Informing │ Upgrade │
+│ CRDs: ReleasePayload │
+└────────────────────────────┬────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ STORAGE & OUTPUT │
+│ GCS (Audit Logs) │ Container Registry │ Kubernetes Secrets │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+## Component Details
+
+### Release Controller Main Components
+
+#### Event Handlers
+
+- **ImageStream Handler**: Watches for changes to source ImageStreams via Kubernetes informers
+- **Job Handler**: Monitors Kubernetes Job completion and triggers release processing
+- **ProwJob Handler**: Tracks ProwJob status updates for verification tests
+- **ReleasePayload Handler**: Responds to ReleasePayload changes and updates
+
+#### Work Queues
+
+- **Main Queue**: Processes release sync operations (rate-limited)
+- **GC Queue**: Handles garbage collection of old releases
+- **Audit Queue**: Manages release auditing (severely rate-limited: 5 per 2 seconds)
+- **Jira Queue**: Updates Jira tickets for fixed issues
+- **Legacy Queue**: Migrates old ImageStream-based results to ReleasePayloads
+
+#### Sync Functions
+
+- **sync()**: Main orchestration function that coordinates all release operations
+- **syncRelease()**: Creates and manages release tags in ImageStreams
+- **syncMirror()**: Creates point-in-time image mirrors to prevent pruning
+- **syncVerify()**: Launches and monitors verification ProwJobs
+- **syncGC()**: Removes old/unused releases and mirrors
+- **syncAudit()**: Audits and signs releases, stores results in GCS
+- **syncJira()**: Updates Jira tickets when releases fix issues
+
+### Release Controller API Components
+
+- **HTTP Server**: Main web server listening on port 8080
+- **Web UI**: HTML interface for browsing releases, viewing graphs, and comparing releases
+- **REST API**: JSON endpoints for programmatic access to release information
+- **Candidate Handler**: Shows candidate releases ready for promotion
+- **Changelog Handler**: Generates release changelogs from commit history
+- **Compare Handler**: Compares two releases to show differences
+- **Graph Visualization**: Displays upgrade paths between releases
+
+### Release Payload Controller Components
+
+#### Payload Controllers
+
+- **Payload Creation**: Updates the payload creation conditions
+- **Payload Verification**: Populates the initial ReleasePayload Status stanza
+- **Payload Accepted**: Updates the payload accepted condition
+- **Payload Rejected**: Updates the payload rejected condition
+- **Payload Mirror**: Monitors release mirror/creation jobs and updates ReleasePayload conditions
+
+#### Job Controllers
+
+- **Job State**: Updates job states in ReleasePayloads based on job completion
+- **Legacy Job Status**: Migrates old job status from ImageStream annotations to ReleasePayloads
+- **Release Creation Job**: Tracks release image creation job status
+- **Release Mirror Job**: Tracks mirror job status and completion
+
+### Data Flow
+
+#### 1. Release Creation Flow
+
+```text
+ART Updates ImageStream
+ → Controller detects change (Informer)
+ → Enqueues to Main Queue
+ → sync() processes
+ → syncMirror() creates mirror (Point-In-Time)
+ → syncRelease() creates release tag
+ → Launches release creation job
+ → Job runs 'oc adm release new'
+ → Release image created
+ → Tag marked as Ready
+ → ReleasePayload CR created
+```
+
+#### 2. Verification Flow
+
+```text
+Release image Ready
+ → syncVerify() reads Prow config
+ → Creates ProwJobs (blocking, informing, upgrade)
+ → Prow executes jobs
+ → Job status updates trigger ReleasePayload updates
+ → All blocking jobs pass → ReleasePayload Accepted
+ → Any blocking job fails → ReleasePayload Rejected
+```
+
+#### 3. Acceptance Flow
+
+```text
+All blocking jobs pass
+ → ReleasePayload condition updated to Accepted
+ → Payload Accepted Controller updates accepted condition
+ → Release available for end users
+```
+
+#### 4. Auditing Flow
+
+```text
+Release tag Ready
+ → Enqueued to Audit Queue (rate-limited)
+ → syncAudit() processes
+ → Launches analysis job
+ → Signs release with GPG keyring
+ → Stores audit logs in GCS
+```
+
+#### 5. API Access Flow
+
+```text
+User requests release info
+ → HTTP Server receives request
+ → Routes to appropriate handler
+ → Handler reads ImageStreams/ReleasePayloads
+ → Uses ReleaseInfo for metadata
+ → Generates response (HTML/JSON)
+ → Returns to user
+```
+
+## Key Interactions
+
+### Between Controllers
+
+- **Release Controller** creates ReleasePayload CRs when new releases are detected
+- **Release Payload Controller** updates ReleasePayload conditions and status based on job results
+- Both controllers monitor the same Kubernetes resources but handle different aspects
+- Controllers use Kubernetes informers for efficient resource watching
+
+### With External Systems
+
+- **Prow**: Controller creates ProwJobs, Prow executes them and reports results
+- **Jira**: Controller reads GitHub PRs to find fixed issues, updates Jira tickets to VERIFIED
+- **Registry**: Controller publishes accepted releases to external container registries
+- **GCS**: Controller stores audit logs and signed release metadata in Google Cloud Storage
+
+### With Kubernetes
+
+- **Informers**: Efficient resource watching with local caching
+- **Work Queues**: Rate-limited processing to prevent overwhelming the cluster
+- **Jobs**: Long-running operations (release creation, analysis)
+- **CRDs**: Custom resource definitions for ReleasePayloads
+- **Secrets**: Stores upgrade graph data persistently
+
+## Sequence Diagram: Release Creation
+
+```mermaid
+sequenceDiagram
+ participant ART
+ participant IS as ImageStream
+ participant RC as Release Controller
+ participant Job as Release Job
+ participant PJ as ProwJobs
+ participant RP as ReleasePayload
+
+ ART->>IS: Update images
+ IS->>RC: Informer event
+ RC->>RC: Enqueue to Main Queue
+ RC->>IS: Create release tag
+ RC->>IS: Create mirror
+ RC->>Job: Launch release creation job
+ Job->>IS: Create release image
+ Job->>RC: Job complete
+ RC->>IS: Mark tag as Ready
+ RC->>RP: Create ReleasePayload
+ RC->>PJ: Create verification ProwJobs
+ PJ->>PJ: Execute tests
+ PJ->>RP: Update job status
+ RP->>RP: Check conditions
+ alt All blocking jobs pass
+ RP->>RP: Mark as Accepted
+ else Any blocking job fails
+ RP->>RP: Mark as Rejected
+ end
+```
+
+## Architecture Decisions
+
+### Why Multiple Controllers?
+
+- **Separation of Concerns**: Each controller handles a specific aspect (core logic, API, CRD management)
+- **Scalability**: Controllers can be scaled independently
+- **Maintainability**: Easier to understand and modify individual components
+
+### Why Multiple Kubeconfigs?
+
+- **Security**: Different permissions for different operations
+- **Isolation**: ProwJobs may need different cluster access than regular jobs
+- **Flexibility**: Allows connecting to different clusters for different purposes
+
+### Why Work Queues?
+
+- **Rate Limiting**: Prevents overwhelming the cluster with too many operations
+- **Retry Logic**: Failed operations can be retried with backoff
+- **Prioritization**: Different queues for different priority operations
+
+### Why ReleasePayloads?
+
+- **Better Observability**: Structured status and conditions
+- **Kubernetes Native**: Uses standard Kubernetes patterns
+- **Extensibility**: Easy to add new fields and conditions
+- **Migration Path**: Moving away from ImageStream annotations
+
+## Performance Considerations
+
+- **Informer Caching**: Reduces API server load by caching resources locally
+- **Rate Limiting**: Prevents controller from overwhelming the cluster
+- **Batch Processing**: Groups related operations together
+- **Async Processing**: Non-blocking operations for better throughput
+
+## Security Considerations
+
+- **Multiple Kubeconfigs**: Least privilege access for different operations
+- **Signing**: Releases are signed with GPG keyrings
+- **Audit Logging**: All operations are logged for compliance
+- **Image Verification**: Only verified releases are signed
diff --git a/docs/BEGINNERS_GUIDE.md b/docs/BEGINNERS_GUIDE.md
new file mode 100644
index 000000000..0f1e7c5a0
--- /dev/null
+++ b/docs/BEGINNERS_GUIDE.md
@@ -0,0 +1,478 @@
+# Release Controller - Beginner's Guide
+
+## Overview
+
+The **release-controller** is a Kubernetes controller system that automates the creation, verification, and management of OpenShift release payloads. It monitors image streams, creates release images, runs verification tests, and publishes release information.
+
+> **Note**: For the canonical documentation, see the [OpenShift Release repository](https://github.com/openshift/release/tree/master/core-services/release-controller).
+
+## What is a Release?
+
+A **release** in OpenShift is a collection of container images that together form a complete, installable version of OpenShift. Each release includes:
+
+- All container images needed to run OpenShift
+- Metadata about the release (version, components, etc.)
+- Upgrade paths between releases
+
+## Target Audience
+
+This guide is designed for:
+
+- New contributors to the release-controller repository
+- Developers who need to understand how releases are created
+- Operators who need to troubleshoot release issues
+- Anyone wanting to understand the OpenShift release process
+
+## Repository Structure
+
+```text
+release-controller/
+├── cmd/ # Main executables
+│ ├── release-controller/ # Core controller (manages releases)
+│ ├── release-controller-api/ # Web UI and API server
+│ ├── release-payload-controller/ # Manages ReleasePayload CRs
+│ └── release-reimport-controller/ # Handles re-importing of imagestreamtags that failed initial import
+├── pkg/ # Shared packages
+│ ├── release-controller/ # Core release logic
+│ ├── releasepayload/ # ReleasePayload CRD logic
+│ ├── jira/ # Jira integration
+│ └── signer/ # Release signing
+└── images/ # Dockerfiles for each component
+```
+
+## Main Components
+
+### 1. Release Controller (`cmd/release-controller/`)
+
+**Purpose**: The core controller that orchestrates the entire release process.
+
+**Key Responsibilities**:
+- Monitors ImageStreams for changes
+- Creates releases when new images are available
+- Mirrors the inbound ImageStreams to create a Point-In-Time release
+- Launches jobs for release-related tasks
+- Manages release verification (ProwJobs)
+- Handles garbage collection of old releases
+- Audits and signs releases
+- Updates Jira tickets for fixed issues
+
+**Key Files**:
+- `main.go`: Entry point, sets up clients and informers
+- `controller.go`: Main controller structure and event handlers
+- `sync.go`: Core sync logic for processing releases
+- `sync_release.go`: Creates and manages release tags
+- `sync_mirror.go`: Handles image stream mirroring
+- `sync_verify.go`: Manages verification jobs
+- `sync_gc.go`: Garbage collection of old releases
+- `audit.go`: Release auditing functionality
+
+### 2. Release Controller API (`cmd/release-controller-api/`)
+
+**Purpose**: Provides a web interface and REST API for viewing releases.
+
+**Key Responsibilities**:
+- Serves web UI for browsing releases
+- Provides REST endpoints for release information
+- Displays upgrade graphs
+- Shows release changelogs
+- Compares releases
+
+**Key Files**:
+- `main.go`: HTTP server setup
+- `http.go`: Main HTTP handlers
+- `http_candidate.go`: Candidate release endpoints
+- `http_changelog.go`: Changelog generation
+- `http_compare.go`: Release comparison
+- `http_upgrade_graph.go`: Upgrade graph visualization
+
+### 3. Release Payload Controller (`cmd/release-payload-controller/`)
+
+**Purpose**: Manages ReleasePayload Custom Resources (CRs).
+
+**Key Responsibilities**:
+- Updates payload creation conditions
+- Monitors release mirror/creation jobs and updates ReleasePayload conditions
+- Populates the initial ReleasePayload Status stanza
+- Updates the payload accepted condition
+- Updates the payload rejected condition
+- Tracks verification job results
+
+**Key Files**:
+- `payload_creation_controller.go`: Updates the payload creation conditions
+- `payload_verification_controller.go`: Populates the initial ReleasePayload Status stanza
+- `payload_accepted_controller.go`: Updates the payload accepted condition
+- `payload_rejected_controller.go`: Updates the payload rejected condition
+- `job_state_controller.go`: Updates job states
+
+### 4. Release Reimport Controller (`cmd/release-reimport-controller/`)
+
+**Purpose**: Handles the re-importing of imagestreamtags that failed their initial import into the inbound ImageStream.
+
+## How It Works
+
+### Release Creation Flow
+
+1. **Image Stream Update**: ART (Automated Release Team) updates an ImageStream (e.g., `ocp/4.15-art-latest`)
+
+2. **Controller Detection**: The release-controller detects the change via Kubernetes informers
+
+3. **Mirror Creation**: Controller creates a point-in-time mirror of the ImageStream to prevent image pruning
+
+4. **Release Tag Creation**: Controller creates a new release tag (e.g., `4.15.0-0.nightly-2024-01-15-123456`)
+
+5. **Release Image Build**: Controller launches a Kubernetes Job that runs `oc adm release new` to create the release image
+
+6. **Verification Jobs**: Once the release image is ready, controller launches ProwJobs for:
+ - Release analysis
+ - Blocking verification tests
+ - Informing verification tests
+ - Upgrade tests (for stable releases)
+
+7. **Status Updates**: Controller monitors job results and updates release status:
+ - `Ready`: Release image created successfully
+ - `Accepted`: All blocking jobs passed
+ - `Rejected`: One or more blocking jobs failed
+ - `Failed`: Release creation or processing failed
+
+### Key Concepts
+
+#### Image Streams
+- **Source ImageStream**: The input ImageStream (e.g., `ocp/4.15-art-latest`) that contains component images
+- **Release ImageStream**: The target ImageStream (e.g., `oc/release`) where release tags are created
+- **Mirror ImageStream**: A point-in-time copy of the source to prevent image pruning
+
+#### Release Phases
+- **Pending**: Release tag created but not yet processed
+- **Ready**: Release image created successfully
+- **Accepted**: All verification tests passed
+- **Rejected**: Verification tests failed
+- **Failed**: Release creation or processing failed
+
+#### Release Payloads vs ImageStream Tags
+
+**ImageStream Tags** (Legacy):
+- Traditional way of tracking releases
+- Stored as tags on ImageStreams
+- Used for backward compatibility
+
+**ReleasePayloads** (Modern):
+- Kubernetes CRs (Custom Resources) that represent releases
+- Created by the release-controller
+- Track job status, conditions, and results
+- Provide better observability and management
+- Migration from ImageStream tags is ongoing
+
+## Configuration
+
+### Release Configuration
+Releases are configured via annotations on ImageStreams:
+
+```yaml
+apiVersion: image.openshift.io/v1
+kind: ImageStream
+metadata:
+ name: 4.15-art-latest
+ namespace: ocp
+ annotations:
+ release.openshift.io/config: |
+ {
+ "name": "4.15",
+ "verify": {
+ "prow": {
+ "optional": [...],
+ "upgrade": [...]
+ }
+ }
+ }
+```
+
+### Controller Flags
+Key flags for `release-controller`:
+- `--release-namespace`: Namespace containing source ImageStreams
+- `--job-namespace`: Namespace for running jobs
+- `--prow-namespace`: Namespace for ProwJobs
+- `--prow-config`: Path to Prow configuration
+- `--release-architecture`: Target architecture (amd64, arm64, etc.)
+- `--dry-run`: Test mode without making changes
+
+## Quick Start
+
+### Prerequisites
+- Go 1.23+ installed
+- Access to a Kubernetes cluster (or `api.ci` for OpenShift CI)
+- `kubectl` or `oc` CLI configured
+- KUBECONFIG pointing to your cluster
+
+### Building and Running Locally
+
+1. **Build the project**:
+ ```bash
+ make
+ ```
+
+2. **Run in dry-run mode** (recommended for testing):
+ ```bash
+ ./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --dry-run \
+ -v=4
+ ```
+
+3. **Access the web UI**:
+ Navigate to `http://localhost:8080` in your browser
+
+4. **View metrics**:
+ Metrics are available at `http://localhost:8080/metrics`
+
+### Running the API Server
+
+```bash
+./release-controller-api \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --port 8080
+```
+
+## API Endpoints
+
+The release-controller-api provides several endpoints:
+
+### Web UI Endpoints
+- `/` - Main release dashboard
+- `/releasestream/{release}` - View a specific release stream
+- `/releasestream/{release}/release/{tag}` - View a specific release
+- `/releasestream/{release}/latest` - Latest release for a stream
+- `/releasestream/{release}/candidates` - Candidate releases
+- `/changelog` - Release changelog
+- `/graph` - Upgrade graph visualization
+- `/dashboards/overview` - Overview dashboard
+- `/dashboards/compare` - Compare releases
+
+### REST API Endpoints
+- `GET /api/v1/releasestream/{release}/tags` - List all tags for a release stream
+- `GET /api/v1/releasestream/{release}/latest` - Get latest release
+- `GET /api/v1/releasestream/{release}/candidate` - Get candidate release
+- `GET /api/v1/releasestream/{release}/release/{tag}` - Get release info
+- `GET /api/v1/releasestream/{release}/config` - Get release configuration
+- `GET /api/v1/releasestreams/accepted` - List accepted streams
+- `GET /api/v1/releasestreams/rejected` - List rejected streams
+- `GET /api/v1/releasestreams/all` - List all streams
+
+### Example API Usage
+
+```bash
+# Get latest release for 4.15
+curl http://localhost:8080/api/v1/releasestream/4.15/latest
+
+# Get all tags for a release stream
+curl http://localhost:8080/api/v1/releasestream/4.15/tags
+
+# Get release information
+curl http://localhost:8080/api/v1/releasestream/4.15/release/4.15.0-0.nightly-2024-01-15-123456
+```
+
+## Common Tasks
+
+### Viewing Releases
+Access the web UI at `http://localhost:8080` (when running locally)
+
+### Checking Release Status
+```bash
+# Check ImageStream tag
+oc get imagestreamtag -n ocp release:4.15.0-0.nightly-2024-01-15-123456
+
+# Check ReleasePayload
+oc get releasepayloads -n ocp
+oc describe releasepayload 4.15.0-0.nightly-2024-01-15-123456 -n ocp
+```
+
+### Viewing Release Payloads
+```bash
+# List all ReleasePayloads
+oc get releasepayloads -n ocp
+
+# Get details of a specific ReleasePayload
+oc get releasepayload 4.15.0-0.nightly-2024-01-15-123456 -n ocp -o yaml
+
+# Check conditions
+oc get releasepayload 4.15.0-0.nightly-2024-01-15-123456 -n ocp -o jsonpath='{.status.conditions}'
+```
+
+### Checking Job Status
+```bash
+# List jobs in job namespace
+oc get jobs -n ci-release
+
+# Check specific job logs
+oc logs job/ -n ci-release
+
+# List ProwJobs
+oc get prowjobs -n ci
+
+# Check ProwJob status
+oc get prowjob -n ci -o yaml
+```
+
+### Viewing Controller Logs
+```bash
+# Release controller logs
+oc logs -n deployment/release-controller
+
+# Release controller API logs
+oc logs -n deployment/release-controller-api
+
+# Release payload controller logs
+oc logs -n deployment/release-payload-controller
+```
+
+## Troubleshooting
+
+### Release Not Created
+
+**Symptoms**: New images in source ImageStream but no release tag created
+
+**Check**:
+1. Verify ImageStream has the `release.openshift.io/config` annotation:
+ ```bash
+ oc get imagestream 4.15-art-latest -n ocp -o yaml | grep release.openshift.io/config
+ ```
+2. Check controller logs for errors:
+ ```bash
+ oc logs -n deployment/release-controller --tail=100
+ ```
+3. Verify controller is watching the correct namespace
+4. Check if release stream has reached end-of-life
+
+### Jobs Failing
+
+**Symptoms**: Release creation job or verification jobs failing
+
+**Check**:
+1. View job logs:
+ ```bash
+ oc logs job/ -n
+ ```
+2. Check job events:
+ ```bash
+ oc describe job -n
+ ```
+3. Verify image pull permissions
+4. Check Prow configuration if ProwJobs are failing
+5. Verify cluster resources (CPU, memory)
+
+### Release Stuck in Pending
+
+**Symptoms**: Release tag created but never moves to Ready state
+
+**Check**:
+1. Verify release creation job completed:
+ ```bash
+ oc get jobs -n | grep
+ ```
+2. Check if image stream mirror was created:
+ ```bash
+ oc get imagestreams -n | grep mirror
+ ```
+3. Check controller logs for errors
+4. Verify job namespace has sufficient resources
+
+### Release Not Accepted
+
+**Symptoms**: Release is Ready but not Accepted
+
+**Check**:
+1. Check ReleasePayload conditions:
+ ```bash
+ oc get releasepayload -n ocp -o jsonpath='{.status.conditions}'
+ ```
+2. Check blocking job status:
+ ```bash
+ oc get prowjobs -n ci -l release.openshift.io/verify=true
+ ```
+3. Review job results in the web UI
+4. Check if any blocking jobs failed
+
+### Controller Not Responding
+
+**Symptoms**: No updates to releases, logs show no activity
+
+**Check**:
+1. Verify controller pod is running:
+ ```bash
+ oc get pods -n | grep release-controller
+ ```
+2. Check for crash loops:
+ ```bash
+ oc describe pod -n
+ ```
+3. Verify kubeconfig permissions
+4. Check for resource constraints (CPU, memory limits)
+
+## Development
+
+### Building
+```bash
+make
+```
+
+### Testing
+```bash
+make test
+```
+
+### Running Tests
+```bash
+go test ./...
+```
+
+### Code Generation
+```bash
+make update-codegen
+make verify-codegen
+```
+
+## Glossary
+
+- **ART (Automated Release Team)**: Team responsible for building and publishing OpenShift component images
+- **ImageStream**: OpenShift resource that tracks container images and provides image tags
+- **Release Payload**: Kubernetes CRD that represents a release and tracks its status
+- **ProwJob**: Job definition used by Prow for running release verification tests
+- **Release Tag**: A specific version of a release (e.g., `4.15.0-0.nightly-2024-01-15-123456`)
+- **Release Image**: A container image containing all components needed for an OpenShift release
+- **Blocking Job**: A verification job that must pass for a release to be accepted
+- **Informing Job**: A verification job that provides information but doesn't block acceptance
+- **Upgrade Graph**: A graph showing valid upgrade paths between releases
+- **Mirror**: A point-in-time copy of an ImageStream to prevent image pruning
+
+## Key Dependencies
+
+- **Kubernetes/OpenShift**: Container orchestration platform
+- **Prow**: System for running release verification tests
+- **ImageStreams**: OpenShift image management
+- **Jira**: Issue tracking (optional, for verification)
+
+## Further Reading
+
+- [OpenShift Release Documentation](https://github.com/openshift/release/tree/master/core-services/release-controller)
+- [Release Tool Documentation](./release-tool.md)
+- [Supply Chain Security](./supply-chain-security.md)
+- [Architecture Diagrams](./ARCHITECTURE_DIAGRAMS.md)
+
+## Getting Help
+
+- Check controller logs: `oc logs -n deployment/release-controller`
+- Review job logs in the job namespace
+- Check ReleasePayload status and conditions
+- Review ImageStream annotations and tags
+- Check the web UI for visual status information
+- Review the [Architecture Diagrams](./ARCHITECTURE_DIAGRAMS.md) for system understanding
+
+## Contributing
+
+When contributing to this repository:
+1. Follow the existing code style
+2. Add tests for new functionality
+3. Update documentation as needed
+4. Ensure all tests pass: `make test`
+5. Verify code generation: `make verify-codegen`
diff --git a/docs/CODEBASE_WALKTHROUGH.md b/docs/CODEBASE_WALKTHROUGH.md
new file mode 100644
index 000000000..8cf741299
--- /dev/null
+++ b/docs/CODEBASE_WALKTHROUGH.md
@@ -0,0 +1,367 @@
+# Codebase Walkthrough
+
+## Repository Structure
+
+The Release Controller repository follows a standard Go project layout:
+
+```
+release-controller/
+├── cmd/ # Command-line tools and applications
+├── pkg/ # Shared libraries and packages
+├── images/ # Container image definitions
+├── hack/ # Build scripts and utilities
+├── docs/ # Documentation (this directory)
+├── test/ # Test files and test data
+├── artifacts/ # Generated artifacts (CRDs)
+├── vendor/ # Vendored dependencies
+├── Makefile # Build automation
+├── go.mod # Go module definition
+├── go.sum # Go module checksums
+├── README.md # Main README
+└── OWNERS # Code owners file
+```
+
+## Directory Details
+
+### `/cmd` - Command-Line Tools
+
+This directory contains all executable components.
+
+#### Core Components
+
+**Release Controller (`cmd/release-controller/`):**
+- `main.go` - Entry point, sets up clients and informers
+- `controller.go` - Main controller structure and event handlers
+- `sync.go` - Core sync logic orchestrating all operations
+- `sync_release.go` - Creates and manages release tags
+- `sync_release_payload.go` - Manages ReleasePayload creation
+- `sync_mirror.go` - Handles image stream mirroring
+- `sync_verify.go` - Manages verification jobs
+- `sync_verify_prow.go` - Prow job verification logic
+- `sync_upgrade.go` - Upgrade graph management
+- `sync_gc.go` - Garbage collection of old releases
+- `sync_tags.go` - Tag management
+- `sync_publish.go` - Release publishing
+- `sync_analysis.go` - Release analysis
+- `audit.go` - Release auditing functionality
+- `jira.go` - Jira integration
+- `periodic.go` - Periodic job management
+- `prune_graph.go` - Upgrade graph pruning
+- `expectations.go` - Release expectations management
+- `cluster_distribution.go` - Cluster distribution logic
+
+**Release Controller API (`cmd/release-controller-api/`):**
+- `main.go` - HTTP server setup
+- `http.go` - Main HTTP handlers
+- `controller.go` - API controller logic
+- `http_candidate.go` - Candidate release endpoints
+- `http_changelog.go` - Changelog generation
+- `http_compare.go` - Release comparison
+- `http_upgrade_graph.go` - Upgrade graph visualization
+- `http_helper.go` - HTTP helper functions
+- `static/` - Static web assets (HTML, CSS, JS)
+
+**Release Payload Controller (`cmd/release-payload-controller/`):**
+- `main.go` - Entry point for payload controller
+
+**Release Reimport Controller (`cmd/release-reimport-controller/`):**
+- `main.go` - Entry point for reimport controller
+
+### `/pkg` - Shared Packages
+
+**Core Release Logic:**
+- `pkg/release-controller/` - Core release controller logic
+ - `release.go` - Release data structures and logic
+ - `release_info.go` - Release information management
+ - `release_payload.go` - ReleasePayload handling
+ - `prowjob.go` - ProwJob integration
+ - `upgrades.go` - Upgrade path logic
+ - `mirror.go` - Image mirroring logic
+ - `cache.go` - Caching utilities
+ - `types.go` - Type definitions
+ - `semver.go` - Semantic versioning
+ - `error.go` - Error handling
+ - `listers.go` - Kubernetes listers
+
+**ReleasePayload Management:**
+- `pkg/releasepayload/` - ReleasePayload CRD logic
+ - `utils.go` - Utility functions
+ - `conditions/` - Condition management
+ - `controller/` - Controller helpers
+ - `jobstatus/` - Job status tracking
+ - `jobrunresult/` - Job run results
+ - `v1alpha1helpers/` - API version helpers
+
+**Release Payload Controller:**
+- `pkg/cmd/release-payload-controller/` - Payload controller implementation
+ - `controller.go` - Main controller
+ - `cmd.go` - Command setup
+ - `config.go` - Configuration
+ - `payload_creation_controller.go` - Payload creation
+ - `payload_mirror_controller.go` - Payload mirroring
+ - `payload_verification_controller.go` - Verification
+ - `payload_accepted_controller.go` - Acceptance logic
+ - `payload_rejected_controller.go` - Rejection logic
+ - `prowjob_controller.go` - ProwJob management
+ - `job_state_controller.go` - Job state tracking
+ - `release_creation_job_controller.go` - Creation jobs
+ - `release_mirror_job_controller.go` - Mirror jobs
+ - `legacy_job_status_controller.go` - Legacy job status
+
+**Release Reimport Controller:**
+- `pkg/cmd/release-reimport-controller/` - Reimport controller
+ - `controller.go` - Reimport logic
+ - `cmd.go` - Command setup
+
+**APIs:**
+- `pkg/apis/release/` - API definitions
+ - `v1alpha1/` - ReleasePayload CRD
+ - `types.go` - CRD type definitions
+ - `register.go` - API registration
+
+**Integrations:**
+- `pkg/jira/` - Jira integration
+- `pkg/signer/` - Release signing
+- `pkg/prow/` - Prow integration utilities
+- `pkg/rhcos/` - RHCOS image handling
+
+**Client Libraries:**
+- `pkg/client/` - Generated Kubernetes clients
+ - `clientset/` - Client set
+ - `informers/` - Informers for watching
+ - `listers/` - Listers for reading
+
+### `/images` - Container Images
+
+Container image definitions for each component:
+- `release-controller/Dockerfile`
+- `release-controller-api/Dockerfile`
+- `release-payload-controller/Dockerfile`
+- `release-reimport-controller/Dockerfile`
+
+### `/hack` - Build Scripts
+
+Utility scripts:
+- `update-codegen.sh` - Code generation
+- `verify-codegen.sh` - Verify generated code
+- `release-tool.py` - Release tooling
+- `tools.go` - Build tools
+
+### `/test` - Test Files
+
+- `test/testdata/` - Test data files
+ - `jobs.yaml` - Test job definitions
+ - `prow.yaml` - Test Prow configs
+
+## Key Files and Modules
+
+### Main Entry Points
+
+**Release Controller (`cmd/release-controller/main.go`):**
+- Initializes Kubernetes clients
+- Sets up informers for ImageStreams and ReleasePayloads
+- Starts controller loops
+- Sets up HTTP server for metrics
+
+**Release Controller API (`cmd/release-controller-api/main.go`):**
+- Sets up HTTP server
+- Registers route handlers
+- Serves static files
+- Provides REST API endpoints
+
+**Release Payload Controller (`cmd/release-payload-controller/main.go`):**
+- Initializes controller manager
+- Registers sub-controllers
+- Starts reconciliation loops
+
+### Core Components
+
+**Sync Logic (`cmd/release-controller/sync.go`):**
+- Main sync function orchestrating all operations
+- Calls individual sync functions
+- Handles errors and retries
+
+**Release Management (`cmd/release-controller/sync_release.go`):**
+- Creates release tags
+- Manages release lifecycle
+- Handles release configuration
+
+**ReleasePayload Management (`cmd/release-controller/sync_release_payload.go`):**
+- Creates ReleasePayload CRs
+- Updates payload status
+- Manages payload conditions
+
+**Mirroring (`cmd/release-controller/sync_mirror.go`):**
+- Mirrors source ImageStreams
+- Creates point-in-time snapshots
+- Manages mirror jobs
+
+**Verification (`cmd/release-controller/sync_verify.go`):**
+- Launches verification jobs
+- Tracks job results
+- Updates verification status
+
+## Component Interactions
+
+### How Release Controller Works
+
+1. **ImageStream Monitoring** (`cmd/release-controller/controller.go`):
+ - Watches ImageStreams via informers
+ - Detects new images or updates
+ - Triggers sync operations
+
+2. **Release Creation** (`cmd/release-controller/sync_release.go`):
+ - Checks release configuration
+ - Creates ReleasePayload if needed
+ - Launches creation job
+
+3. **Payload Management** (`cmd/release-controller/sync_release_payload.go`):
+ - Creates ReleasePayload CR
+ - Updates payload status
+ - Manages payload lifecycle
+
+4. **Verification** (`cmd/release-controller/sync_verify.go`):
+ - Launches ProwJobs for verification
+ - Monitors job results
+ - Updates payload status
+
+5. **Publishing** (`cmd/release-controller/sync_publish.go`):
+ - Publishes releases to registry
+ - Updates release tags
+ - Makes releases available
+
+### How Release Payload Controller Works
+
+1. **Payload Creation Controller**:
+ - Watches ReleasePayloads
+ - Monitors creation jobs
+ - Updates creation conditions
+
+2. **ProwJob Controller**:
+ - Watches ProwJobs
+ - Updates payload with job results
+ - Manages verification status
+
+3. **Payload Accepted Controller**:
+ - Checks acceptance criteria
+ - Updates accepted condition
+ - Triggers publishing
+
+4. **Payload Rejected Controller**:
+ - Checks rejection criteria
+ - Updates rejected condition
+ - Blocks publishing
+
+## Key Classes and Functions
+
+### Release Controller Core
+
+**Main Function** (`cmd/release-controller/main.go:main`):
+- Entry point for release controller
+- Parses flags and configuration
+- Initializes clients
+- Starts controller
+
+**Sync Function** (`cmd/release-controller/sync.go:sync`):
+- Main sync orchestration
+- Calls individual sync functions
+- Handles errors
+
+**Release Creation** (`cmd/release-controller/sync_release.go`):
+- `syncRelease()` - Creates releases
+- `createRelease()` - Creates release tags
+- `shouldCreateRelease()` - Determines if release needed
+
+**Payload Management** (`cmd/release-controller/sync_release_payload.go`):
+- `syncReleasePayload()` - Syncs payload state
+- `createReleasePayload()` - Creates payload CR
+- `updateReleasePayload()` - Updates payload status
+
+### Release Payload Controller
+
+**Controller Manager** (`pkg/cmd/release-payload-controller/controller.go`):
+- Manages multiple sub-controllers
+- Coordinates reconciliation
+- Handles errors
+
+**Payload Creation** (`pkg/cmd/release-payload-controller/payload_creation_controller.go`):
+- `Reconcile()` - Reconciles payload creation
+- Monitors creation jobs
+- Updates conditions
+
+## API Surface
+
+### ReleasePayload API
+
+**Custom Resource** (`pkg/apis/release/v1alpha1/types.go`):
+```go
+type ReleasePayload struct {
+ Spec ReleasePayloadSpec
+ Status ReleasePayloadStatus
+}
+
+type ReleasePayloadSpec struct {
+ ReleaseTag string
+ // ...
+}
+
+type ReleasePayloadStatus struct {
+ Conditions []metav1.Condition
+ // ...
+}
+```
+
+### Release Controller API
+
+**HTTP Endpoints** (`cmd/release-controller-api/http.go`):
+- `/` - Main dashboard
+- `/releases` - Release listings
+- `/release/{tag}` - Release details
+- `/changelog` - Changelog generation
+- `/compare` - Release comparison
+- `/upgrade-graph` - Upgrade graph
+
+## Data Flow
+
+1. **Release Creation Flow:**
+ - ImageStream updated
+ - Controller detects change
+ - ReleasePayload created
+ - Creation job launched
+ - Release image created
+ - Verification jobs launched
+ - Payload status updated
+
+2. **Verification Flow:**
+ - ProwJobs created
+ - Jobs execute
+ - Results collected
+ - Payload status updated
+ - Acceptance/rejection determined
+
+3. **Publishing Flow:**
+ - Release accepted
+ - Release published to registry
+ - Tags updated
+ - Web UI updated
+
+## Testing Structure
+
+- **Unit Tests**: `*_test.go` files alongside source
+- **Integration Tests**: Test data in `test/testdata/`
+- **Test Utilities**: Helper functions in test files
+
+## Build System
+
+- **Makefile**: Main build automation
+- **Go Modules**: Dependency management
+- **Code Generation**: CRD and client generation
+- **Container Builds**: Dockerfile-based
+
+## Extension Points
+
+1. **Custom Controllers**: Add to controller manager
+2. **Custom Sync Functions**: Add to sync.go
+3. **Custom API Endpoints**: Add to API server
+4. **Custom Verification**: Extend verification logic
+
diff --git a/docs/CONTRIBUTING_GUIDE.md b/docs/CONTRIBUTING_GUIDE.md
new file mode 100644
index 000000000..04acb84b8
--- /dev/null
+++ b/docs/CONTRIBUTING_GUIDE.md
@@ -0,0 +1,288 @@
+# Contributing Guide
+
+Thank you for your interest in contributing to Release Controller! This guide will help you understand how to contribute effectively.
+
+## How to Contribute
+
+### 1. Fork and Clone
+
+```bash
+# Fork the repository on GitHub, then clone your fork
+git clone https://github.com/YOUR_USERNAME/release-controller.git
+cd release-controller
+
+# Add upstream remote
+git remote add upstream https://github.com/openshift/release-controller.git
+```
+
+### 2. Create a Branch
+
+```bash
+# Create a feature branch from main
+git checkout -b feature/my-feature
+
+# Or a bugfix branch
+git checkout -b fix/bug-description
+```
+
+### 3. Make Your Changes
+
+- Write clear, readable code
+- Follow Go conventions and style
+- Add tests for new functionality
+- Update documentation as needed
+
+### 4. Test Your Changes
+
+```bash
+# Run unit tests
+go test ./...
+
+# Build components
+make build
+
+# Verify code generation (if changed APIs)
+make verify-codegen
+```
+
+### 5. Commit Your Changes
+
+```bash
+# Stage changes
+git add .
+
+# Commit with descriptive message
+git commit -m "Add feature: description of changes"
+```
+
+**Commit Message Guidelines:**
+- Use imperative mood ("Add feature" not "Added feature")
+- Keep first line under 72 characters
+- Add detailed description if needed
+- Reference issues: "Fix #123: description"
+
+### 6. Push and Create Pull Request
+
+```bash
+# Push to your fork
+git push origin feature/my-feature
+```
+
+Then create a Pull Request on GitHub with:
+- Clear title and description
+- Reference to related issues
+- Screenshots/logs if applicable
+- Checklist of what was tested
+
+## Branching Model
+
+### Branch Naming
+
+- `feature/description` - New features
+- `fix/description` - Bug fixes
+- `docs/description` - Documentation updates
+- `refactor/description` - Code refactoring
+- `test/description` - Test improvements
+
+### Branch Strategy
+
+- **main** - Production-ready code
+- **Feature branches** - Created from main, merged back via PR
+
+## Coding Standards
+
+### Go Style
+
+Follow [Effective Go](https://golang.org/doc/effective_go) and [Go Code Review Comments](https://github.com/golang/go/wiki/CodeReviewComments).
+
+**Formatting:**
+```bash
+# Use gofmt
+go fmt ./...
+
+# Or goimports (handles imports)
+goimports -w .
+```
+
+**Key Guidelines:**
+- Use `gofmt` for formatting
+- Run `goimports` to organize imports
+- Follow naming conventions
+- Keep functions focused and small
+- Add comments for exported functions/types
+
+### Code Organization
+
+- **Packages**: Group related functionality
+- **Files**: Keep files focused
+- **Tests**: `*_test.go` files alongside source
+- **Test Data**: Use `test/testdata/` directories
+
+### Error Handling
+
+```go
+// Good: Wrap errors with context
+if err != nil {
+ return fmt.Errorf("failed to create release: %w", err)
+}
+
+// Good: Use errors.Is and errors.As
+if errors.Is(err, os.ErrNotExist) {
+ // handle
+}
+```
+
+### Logging
+
+```go
+// Use klog for logging
+import "k8s.io/klog"
+
+klog.V(4).Infof("Creating release: %s", releaseTag)
+klog.Errorf("Failed to create release: %v", err)
+```
+
+### Testing
+
+**Unit Tests:**
+```go
+func TestFunction(t *testing.T) {
+ // Arrange
+ input := "test"
+
+ // Act
+ result := Function(input)
+
+ // Assert
+ if result != expected {
+ t.Errorf("Expected %v, got %v", expected, result)
+ }
+}
+```
+
+## PR Guidelines
+
+### PR Requirements
+
+1. **Description**: Clear description of what and why
+2. **Tests**: All tests pass
+3. **Code Generation**: Verify codegen if APIs changed
+4. **Documentation**: Updated if needed
+5. **Size**: Keep PRs focused and reasonably sized
+
+### PR Template
+
+```markdown
+## Description
+Brief description of changes
+
+## Problem
+What problem does this solve?
+
+## Solution
+How does this solve the problem?
+
+## Testing
+- [ ] Unit tests added/updated
+- [ ] Manual testing performed
+- [ ] Code generation verified (if APIs changed)
+
+## Related Issues
+Fixes #123
+Related to #456
+```
+
+### Review Process
+
+1. **Automated Checks**: Must pass (tests, codegen, etc.)
+2. **Code Review**: At least one approval required
+3. **LGTM**: Reviewer says `/lgtm` when satisfied
+4. **Approve**: Approver says `/approve` for final approval
+5. **Merge**: Automated merge when all conditions met
+
+## Code Review Guidelines
+
+### For Reviewers
+
+**What to Look For:**
+- Code correctness and logic
+- Test coverage
+- Error handling
+- Performance considerations
+- Security implications
+- Documentation completeness
+
+**Review Checklist:**
+- [ ] Code follows style guidelines
+- [ ] Tests are adequate
+- [ ] Error handling is proper
+- [ ] Documentation is updated
+- [ ] No security issues
+- [ ] Performance is acceptable
+
+### For Authors
+
+**Before Requesting Review:**
+- Self-review your code
+- Run all tests
+- Verify code generation
+- Update documentation
+- Write clear PR description
+
+**During Review:**
+- Respond promptly to comments
+- Be open to suggestions
+- Ask for clarification if needed
+- Update code based on feedback
+
+## Testing Requirements
+
+### Unit Tests
+
+- Required for new functionality
+- Aim for >80% coverage for new code
+- Test edge cases and error conditions
+
+### Integration Tests
+
+- Required for components that modify external state
+- Use test data in `test/testdata/`
+- Test with real Kubernetes clusters when possible
+
+## Documentation
+
+### Code Documentation
+
+- Document exported functions/types
+- Use Go doc comments
+- Include examples for complex APIs
+
+### User Documentation
+
+- Update README.md for component changes
+- Add examples for new features
+- Update this contributing guide if process changes
+
+## Getting Help
+
+### Communication Channels
+
+- **GitHub Issues**: Bug reports and feature requests
+- **Pull Requests**: Code contributions and discussions
+- **Slack**: #forum-testplatform (for OpenShift team members)
+
+### Resources
+
+- [Go Documentation](https://golang.org/doc/)
+- [Kubernetes Contributing Guide](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md)
+- [OpenShift CI Documentation](https://docs.ci.openshift.org/)
+
+## Code of Conduct
+
+- Be respectful and inclusive
+- Welcome newcomers
+- Focus on constructive feedback
+- Follow the [Kubernetes Code of Conduct](https://github.com/kubernetes/community/blob/master/code-of-conduct.md)
+
+Thank you for contributing to Release Controller! 🎉
+
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 000000000..c87ecb18d
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,228 @@
+# FAQ Section
+
+Frequently asked questions from newcomers to the Release Controller repository.
+
+## General Questions
+
+### What is Release Controller?
+
+Release Controller is a Kubernetes-based system that automates the creation, verification, and management of OpenShift release payloads. It monitors image streams, creates release images, runs verification tests, and publishes release information.
+
+### Who maintains Release Controller?
+
+The OpenShift Release Engineering team maintains Release Controller. See the [OWNERS](../OWNERS) file for the list of maintainers.
+
+### What programming language is Release Controller written in?
+
+Go (100%).
+
+### How do I get started?
+
+1. Read the [Overview](OVERVIEW.md)
+2. Set up your environment ([Setup Guide](SETUP.md))
+3. Try running release controller ([Usage Guide](USAGE.md))
+4. Explore the codebase ([Codebase Walkthrough](CODEBASE_WALKTHROUGH.md))
+
+## Development Questions
+
+### How do I build the project?
+
+```bash
+# Build all components
+make build
+
+# Build specific component
+go build ./cmd/release-controller
+```
+
+### How do I run tests?
+
+```bash
+# Run all unit tests
+go test ./...
+
+# Run specific package tests
+go test ./pkg/release-controller/...
+```
+
+### How do I contribute?
+
+See the [Contributing Guide](CONTRIBUTING_GUIDE.md) for detailed instructions. In short:
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Test your changes
+5. Create a Pull Request
+
+## Component Questions
+
+### What is release-controller?
+
+The main controller that orchestrates the entire release process. It monitors ImageStreams, creates releases, manages verification, and publishes releases.
+
+### What is release-controller-api?
+
+The web UI and REST API server that provides a user interface for viewing releases and release information.
+
+### What is release-payload-controller?
+
+A controller that manages ReleasePayload Custom Resources, tracking release creation, verification, and acceptance status.
+
+### What is release-reimport-controller?
+
+A controller that handles re-importing ImageStreamTags that failed initial import.
+
+## Configuration Questions
+
+### How do I configure Release Controller?
+
+Release Controller uses configurations stored in the `openshift/release` repository at `core-services/release-controller/_releases/`.
+
+### How do I add a new release stream?
+
+Add a release configuration file to `openshift/release/core-services/release-controller/_releases/`.
+
+### What is a ReleasePayload?
+
+ReleasePayload is a Custom Resource that tracks the state of a release, including creation progress, verification status, and acceptance/rejection.
+
+## Release Questions
+
+### How are releases created?
+
+1. ImageStreams are updated with new images
+2. Release Controller detects the changes
+3. ReleasePayload is created
+4. Creation job is launched
+5. Release image is assembled
+6. Verification jobs are launched
+7. Release is published when accepted
+
+### How do I check release status?
+
+```bash
+# Get ReleasePayload
+kubectl get releasepayload -n
+
+# Check conditions
+kubectl get releasepayload -n \
+ -o jsonpath='{.status.conditions}'
+```
+
+### What are verification jobs?
+
+ProwJobs that test releases to ensure they work correctly. They verify installation, upgrade paths, and functionality.
+
+### How do releases get published?
+
+When a release passes all verification jobs and meets acceptance criteria, it is automatically published to the container registry and made available.
+
+## Troubleshooting Questions
+
+### Release is not being created
+
+1. Check ImageStream exists and is updated
+2. Verify release configuration is correct
+3. Check controller logs for errors
+4. Verify namespace permissions
+
+### Verification jobs are failing
+
+1. Check ProwJob status
+2. Review job logs
+3. Verify test configurations
+4. Check cluster resources
+
+### Release is not published
+
+1. Check ReleasePayload acceptance conditions
+2. Verify all verification jobs passed
+3. Check publish configuration
+4. Review controller logs
+
+### API is not responding
+
+1. Check API server is running
+2. Verify kubeconfig is correct
+3. Check network connectivity
+4. Review API server logs
+
+## Architecture Questions
+
+### How does Release Controller work?
+
+1. Monitors ImageStreams for changes
+2. Creates ReleasePayload when new images available
+3. Launches creation job to assemble release
+4. Launches verification jobs to test release
+5. Publishes release when accepted
+
+### How are releases verified?
+
+Releases are verified through ProwJobs that test installation, upgrades, and functionality. Results are tracked in the ReleasePayload status.
+
+### How does image mirroring work?
+
+Source ImageStreams are mirrored to release ImageStreams to create point-in-time snapshots. Mirror jobs copy images between streams.
+
+### How does the upgrade graph work?
+
+The upgrade graph tracks valid upgrade paths between releases. It's built from release metadata and validated during release creation.
+
+## Contribution Questions
+
+### How do I find good first issues?
+
+Look for issues labeled:
+- `good first issue`
+- `help wanted`
+- `beginner friendly`
+
+### What makes a good PR?
+
+- Clear description
+- Focused changes
+- Tests included
+- Documentation updated
+- All checks passing
+
+### How long does review take?
+
+Typically 1-3 business days, depending on:
+- PR size and complexity
+- Reviewer availability
+- Number of review rounds needed
+
+## Getting Help
+
+### Where can I ask questions?
+
+- **GitHub Issues**: For bugs and feature requests
+- **Pull Requests**: For code-related questions
+- **Slack**: #forum-testplatform (for OpenShift team members)
+- **Documentation**: Check the docs in this directory
+
+### How do I report a bug?
+
+Create a GitHub issue with:
+- Clear description
+- Steps to reproduce
+- Expected vs actual behavior
+- Relevant logs/configs
+- Environment information
+
+### How do I request a feature?
+
+Create a GitHub issue with:
+- Problem description
+- Proposed solution
+- Use cases
+- Any alternatives considered
+
+## Still Have Questions?
+
+- Check the [documentation index](README.md)
+- Search existing GitHub issues
+- Ask in #forum-testplatform on Slack
+- Create a new issue with your question
+
diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md
new file mode 100644
index 000000000..ac74e3529
--- /dev/null
+++ b/docs/ONBOARDING.md
@@ -0,0 +1,351 @@
+# Onboarding Guide for New Contributors
+
+Welcome to Release Controller! This guide will help you understand the codebase and get started contributing effectively.
+
+## What to Learn Before Contributing
+
+### Essential Knowledge
+
+1. **Go Programming Language**
+ - Go basics (variables, functions, structs, interfaces)
+ - Go concurrency (goroutines, channels)
+ - Go testing (`testing` package)
+ - Go modules and dependency management
+ - **Resources**: [A Tour of Go](https://tour.golang.org/), [Effective Go](https://golang.org/doc/effective_go)
+
+2. **Kubernetes/OpenShift**
+ - Kubernetes API concepts
+ - Custom Resources (CRDs)
+ - Pods, Jobs, ImageStreams
+ - Controllers and Operators
+ - **Resources**: [Kubernetes Documentation](https://kubernetes.io/docs/), [OpenShift Documentation](https://docs.openshift.com/)
+
+3. **OpenShift ImageStreams**
+ - ImageStream concepts
+ - ImageStreamTags
+ - Image mirroring
+ - **Resources**: [OpenShift ImageStreams](https://docs.openshift.com/container-platform/latest/openshift_images/image-streams-manage.html)
+
+4. **Release Concepts**
+ - What is a release payload
+ - Release lifecycle
+ - Release verification
+ - **Resources**: [OpenShift Release Documentation](https://github.com/openshift/release/tree/master/core-services/release-controller)
+
+### Recommended Knowledge
+
+1. **Kubernetes Controllers**
+ - Controller pattern
+ - Reconciliation loops
+ - Informers and listers
+ - **Resources**: [Kubernetes Controller Pattern](https://kubernetes.io/docs/concepts/architecture/controller/)
+
+2. **Prow Integration**
+ - ProwJobs
+ - Job execution
+ - **Resources**: [Prow Documentation](https://docs.prow.k8s.io/)
+
+3. **Container Images**
+ - Container image concepts
+ - Image registries
+ - Image signing
+ - **Resources**: [OCI Image Specification](https://github.com/opencontainers/image-spec)
+
+## Important Concepts the Repo Uses
+
+### 1. ReleasePayload Custom Resource
+
+Release Controller uses a Custom Resource to track release state:
+
+```go
+// From pkg/apis/release/v1alpha1/types.go
+type ReleasePayload struct {
+ Spec ReleasePayloadSpec
+ Status ReleasePayloadStatus
+}
+```
+
+**Key Concepts:**
+- ReleasePayloads track release creation and verification
+- Status contains conditions for different states
+- Controllers reconcile payload state
+
+**Learn More:**
+- Study `pkg/apis/release/v1alpha1/types.go`
+- Read about Kubernetes CRDs
+
+### 2. Controller Pattern
+
+All components follow the Kubernetes controller pattern:
+
+```go
+// Controllers watch resources and reconcile state
+func (c *Controller) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+ // Fetch resource
+ // Reconcile desired state
+ // Update status
+ return ctrl.Result{}, nil
+}
+```
+
+**Key Concepts:**
+- Watch for resource changes
+- Reconcile desired state
+- Handle errors gracefully
+
+**Learn More:**
+- Study `cmd/release-controller/controller.go`
+- Study `pkg/cmd/release-payload-controller/`
+- Read [Kubernetes Controller Pattern](https://kubernetes.io/docs/concepts/architecture/controller/)
+
+### 3. ImageStream-Based Releases
+
+Releases are built from ImageStreams:
+
+**Key Concepts:**
+- Source ImageStreams contain built images
+- Release ImageStreams contain release images
+- Mirroring creates point-in-time snapshots
+- Tags represent releases
+
+**Learn More:**
+- Study `cmd/release-controller/sync_mirror.go`
+- Study `pkg/release-controller/mirror.go`
+- Read about OpenShift ImageStreams
+
+### 4. Job-Based Execution
+
+Release operations execute as Kubernetes Jobs:
+
+**Key Concepts:**
+- Creation jobs assemble releases
+- Mirror jobs copy images
+- Verification jobs test releases
+- Jobs are independent and retryable
+
+**Learn More:**
+- Study `cmd/release-controller/sync_release.go`
+- Study job creation logic
+
+### 5. Verification System
+
+Releases are verified through ProwJobs:
+
+**Key Concepts:**
+- ProwJobs test releases
+- Results tracked in ReleasePayload
+- Acceptance based on verification results
+
+**Learn More:**
+- Study `cmd/release-controller/sync_verify.go`
+- Study `pkg/cmd/release-payload-controller/payload_verification_controller.go`
+
+### 6. Sync Pattern
+
+The main controller uses a sync pattern:
+
+**Key Concepts:**
+- Main sync function orchestrates operations
+- Individual sync functions handle specific tasks
+- Errors are handled and logged
+- Status is updated after operations
+
+**Learn More:**
+- Study `cmd/release-controller/sync.go`
+- Study individual sync functions
+
+## Beginner Roadmap for Mastering the Project
+
+### Phase 1: Understanding the Basics (Week 1-2)
+
+**Goal**: Understand what Release Controller does and how it's organized
+
+**Tasks:**
+1. Read [Overview](OVERVIEW.md) and [Architecture](ARCHITECTURE.md)
+2. Set up development environment ([Setup Guide](SETUP.md))
+3. Build and run release controller locally
+4. Read through `cmd/release-controller/main.go` to understand entry point
+5. Study a simple sync function like `sync_gc.go`
+
+**Deliverable**: You can build and run release controller locally
+
+### Phase 2: Understanding Release Creation (Week 3-4)
+
+**Goal**: Understand how releases are created
+
+**Tasks:**
+1. Read release creation documentation
+2. Study `cmd/release-controller/sync_release.go` to understand release creation
+3. Study `cmd/release-controller/sync_release_payload.go` to understand payload creation
+4. Study `pkg/release-controller/release.go` to understand release data structures
+5. Trace through a release creation flow
+6. Create a test release locally
+
+**Deliverable**: You understand how releases are created
+
+### Phase 3: Understanding Verification (Week 5-6)
+
+**Goal**: Understand how releases are verified
+
+**Tasks:**
+1. Study `cmd/release-controller/sync_verify.go` to understand verification
+2. Study `pkg/cmd/release-payload-controller/payload_verification_controller.go`
+3. Study ProwJob integration
+4. Understand verification job lifecycle
+5. Make a small change to verification logic
+
+**Deliverable**: You can modify verification logic
+
+### Phase 4: Understanding Controllers (Week 7-8)
+
+**Goal**: Understand the controller architecture
+
+**Tasks:**
+1. Study `pkg/cmd/release-payload-controller/` to understand payload controller
+2. Study individual sub-controllers
+3. Understand controller reconciliation
+4. Run a controller locally and observe behavior
+5. Make a small change to a controller
+
+**Deliverable**: You understand how controllers work
+
+### Phase 5: Making Your First Contribution (Week 9-10)
+
+**Goal**: Make your first meaningful contribution
+
+**Tasks:**
+1. Find a good first issue (labeled "good first issue")
+2. Understand the problem and proposed solution
+3. Implement the fix or feature
+4. Write tests
+5. Create a Pull Request
+6. Address review feedback
+
+**Deliverable**: Your first merged PR!
+
+## Learning Resources by Topic
+
+### Go
+
+- **Books**: "The Go Programming Language" by Donovan & Kernighan
+- **Online**: [Go by Example](https://gobyexample.com/)
+- **Practice**: [Exercism Go Track](https://exercism.org/tracks/go)
+
+### Kubernetes
+
+- **Official Docs**: [Kubernetes Documentation](https://kubernetes.io/docs/)
+- **Interactive**: [Kubernetes Playground](https://www.katacoda.com/courses/kubernetes)
+- **Books**: "Kubernetes: Up and Running" by Hightower et al.
+
+### OpenShift
+
+- **Official Docs**: [OpenShift Documentation](https://docs.openshift.com/)
+- **ImageStreams**: [Managing ImageStreams](https://docs.openshift.com/container-platform/latest/openshift_images/image-streams-manage.html)
+
+### Release Management
+
+- **OpenShift Release**: [Release Repository](https://github.com/openshift/release/tree/master/core-services/release-controller)
+- **Release Process**: Internal OpenShift documentation
+
+## Common Patterns in the Codebase
+
+### 1. Sync Pattern
+
+```go
+func (c *Controller) sync() error {
+ // Sync releases
+ if err := c.syncReleases(); err != nil {
+ return err
+ }
+
+ // Sync payloads
+ if err := c.syncReleasePayloads(); err != nil {
+ return err
+ }
+
+ // Sync verification
+ if err := c.syncVerification(); err != nil {
+ return err
+ }
+
+ return nil
+}
+```
+
+### 2. Controller Reconciliation Pattern
+
+```go
+func (r *Reconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {
+ // Fetch resource
+ payload := &releasev1alpha1.ReleasePayload{}
+ if err := r.Get(ctx, req.NamespacedName, payload); err != nil {
+ return ctrl.Result{}, err
+ }
+
+ // Reconcile desired state
+ if err := r.reconcilePayload(payload); err != nil {
+ return ctrl.Result{}, err
+ }
+
+ // Update status
+ return ctrl.Result{}, r.Status().Update(ctx, payload)
+}
+```
+
+### 3. Job Creation Pattern
+
+```go
+func (c *Controller) createJob(spec *batchv1.JobSpec) (*batchv1.Job, error) {
+ job := &batchv1.Job{
+ ObjectMeta: metav1.ObjectMeta{
+ Name: generateJobName(),
+ Namespace: c.jobNamespace,
+ },
+ Spec: *spec,
+ }
+
+ return c.jobClient.Create(context.TODO(), job, metav1.CreateOptions{})
+}
+```
+
+### 4. Error Handling Pattern
+
+```go
+// Wrap errors with context
+if err != nil {
+ return fmt.Errorf("failed to create release: %w", err)
+}
+
+// Use errors.Is for error checking
+if errors.Is(err, imagev1.ErrImageStreamNotFound) {
+ // handle
+}
+```
+
+## Tips for Success
+
+1. **Start Small**: Begin with small, focused changes
+2. **Read Code**: Spend time reading existing code before writing new code
+3. **Ask Questions**: Don't hesitate to ask for help
+4. **Write Tests**: Always write tests for new code
+5. **Review PRs**: Review other PRs to learn patterns
+6. **Be Patient**: Understanding a large codebase takes time
+
+## Getting Help
+
+- **GitHub Issues**: Search existing issues or create new ones
+- **Pull Requests**: Ask questions in PR comments
+- **Slack**: #forum-testplatform (for OpenShift team members)
+- **Documentation**: Read the docs in this directory
+
+## Next Steps
+
+After completing the roadmap:
+
+1. Find areas of interest
+2. Look for issues labeled "good first issue"
+3. Start contributing regularly
+4. Consider becoming a maintainer (after significant contributions)
+
+Welcome to the team! 🚀
+
diff --git a/docs/OVERVIEW.md b/docs/OVERVIEW.md
new file mode 100644
index 000000000..fffc3c310
--- /dev/null
+++ b/docs/OVERVIEW.md
@@ -0,0 +1,149 @@
+# Release Controller: High-Level Overview
+
+## What is Release Controller?
+
+Release Controller is a Kubernetes-based system that automates the creation, verification, and management of OpenShift release payloads. It monitors image streams, creates release images, runs verification tests, publishes release information, and manages the entire release lifecycle for OpenShift.
+
+## What Problem Does It Solve?
+
+OpenShift releases are complex collections of hundreds of container images that must be:
+- **Coordinated**: All images must be built and tested together
+- **Verified**: Releases must pass comprehensive test suites
+- **Published**: Releases must be made available to users
+- **Tracked**: Release status and metadata must be maintained
+- **Audited**: Releases must be signed and auditable
+- **Managed**: Old releases must be garbage collected
+
+Managing this manually would be:
+- Error-prone due to the complexity
+- Time-consuming for release engineers
+- Difficult to track and audit
+- Inconsistent across releases
+
+Release Controller solves these problems by providing automated orchestration of the entire release process, ensuring consistency, reliability, and traceability.
+
+## Who Is It For?
+
+### Primary Users
+
+1. **OpenShift Release Engineering Team**: The team responsible for creating and managing OpenShift releases
+2. **OpenShift Test Platform (TP) Team**: Teams maintaining the CI infrastructure that feeds releases
+3. **OpenShift Developers**: Developers who need to understand how their changes become part of releases
+4. **Release Operators**: Operators who need to troubleshoot release issues
+
+### Skill Level Requirements
+
+- **Basic Users**: Need to understand Kubernetes concepts and YAML configuration
+- **Advanced Users**: Should be familiar with Kubernetes controllers, OpenShift ImageStreams, and CI/CD pipelines
+- **Contributors**: Need strong Go skills, Kubernetes API knowledge, and understanding of release processes
+
+## Key Features
+
+### 1. Release Creation
+- Monitors ImageStreams for new images
+- Creates release payloads from image collections
+- Generates release metadata and manifests
+- Handles multi-architecture releases
+
+### 2. Release Verification
+- Launches ProwJobs for release verification
+- Tracks verification job results
+- Manages release acceptance criteria
+- Handles verification failures
+
+### 3. Release Publishing
+- Publishes releases to container registries
+- Creates release tags and metadata
+- Updates release streams
+- Manages release visibility
+
+### 4. Release Payload Management
+- Manages ReleasePayload Custom Resources
+- Tracks payload creation status
+- Handles payload acceptance/rejection
+- Manages payload lifecycle
+
+### 5. Image Mirroring
+- Mirrors source ImageStreams to release streams
+- Creates point-in-time snapshots
+- Handles multi-registry scenarios
+- Manages mirror job execution
+
+### 6. Upgrade Graph Management
+- Builds upgrade graphs between releases
+- Validates upgrade paths
+- Manages upgrade recommendations
+- Tracks upgrade compatibility
+
+### 7. Garbage Collection
+- Removes old releases based on policies
+- Manages release retention
+- Cleans up unused resources
+- Handles soft deletion
+
+### 8. Auditing and Signing
+- Audits release creation process
+- Signs releases for security
+- Tracks audit logs
+- Manages signing keys
+
+### 9. Web Interface
+- Web UI for browsing releases
+- REST API for programmatic access
+- Release comparison tools
+- Upgrade graph visualization
+
+### 10. Jira Integration
+- Updates Jira tickets for fixed issues
+- Tracks release-related issues
+- Manages release blockers
+
+## Technology Stack
+
+- **Language**: Go (100%)
+- **Platform**: Kubernetes/OpenShift
+- **Storage**: Kubernetes ImageStreams, GCS for artifacts
+- **CI Integration**: Prow for verification jobs
+- **Container Registry**: OpenShift Image Registry, Quay.io
+- **Frontend**: HTML templates with JavaScript
+
+## Repository Statistics
+
+- **License**: Apache-2.0
+- **Main Components**: 4 main executables
+- **Custom Resources**: ReleasePayload CRD
+- **Maintainers**: OpenShift Release Engineering Team
+
+## Key Components
+
+### Core Components
+
+1. **release-controller** - Main controller orchestrating releases
+2. **release-controller-api** - Web UI and REST API server
+3. **release-payload-controller** - Manages ReleasePayload CRs
+4. **release-reimport-controller** - Handles failed image imports
+
+### Supporting Components
+
+- **ReleasePayload CRD** - Custom resource for release tracking
+- **Jira Integration** - Issue tracking and updates
+- **Signer** - Release signing functionality
+- **Audit Backends** - File and GCS audit storage
+
+## Related Documentation
+
+- [OpenShift Release Repository](https://github.com/openshift/release/tree/master/core-services/release-controller) - Canonical documentation
+- [OpenShift CI Documentation](https://docs.ci.openshift.org/)
+- [Prow Documentation](https://docs.prow.k8s.io/)
+
+## Getting Started
+
+For new users, we recommend starting with:
+1. [Setup Guide](SETUP.md) - Get your development environment ready
+2. [Usage Guide](USAGE.md) - Learn how to use the release controller
+3. [Codebase Walkthrough](CODEBASE_WALKTHROUGH.md) - Understand the structure
+
+For contributors:
+1. [Contributing Guide](CONTRIBUTING_GUIDE.md) - Learn how to contribute
+2. [Onboarding Guide](ONBOARDING.md) - Deep dive into the codebase
+
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..8b757a09c
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,96 @@
+# Release Controller Documentation
+
+Welcome to the Release Controller documentation! This directory contains comprehensive documentation for understanding, using, and contributing to Release Controller.
+
+## Documentation Index
+
+### Getting Started
+
+- **[Overview](OVERVIEW.md)** - High-level overview of what Release Controller is, what problems it solves, and who it's for
+- **[Setup Guide](SETUP.md)** - Step-by-step instructions for setting up your development environment
+- **[Usage Guide](USAGE.md)** - Practical examples and instructions for using Release Controller
+
+### Understanding the Codebase
+
+- **[Architecture](ARCHITECTURE.md)** - System architecture, component diagrams, and design patterns
+- **[Codebase Walkthrough](CODEBASE_WALKTHROUGH.md)** - Detailed explanation of the repository structure and key components
+
+### Contributing
+
+- **[Contributing Guide](CONTRIBUTING_GUIDE.md)** - How to contribute, coding standards, and PR guidelines
+- **[Onboarding Guide](ONBOARDING.md)** - Learning path for new contributors, important concepts, and beginner roadmap
+
+### Reference
+
+- **[FAQ](FAQ.md)** - Frequently asked questions and answers
+- **[Summaries](SUMMARIES.md)** - Summaries at different technical levels (non-technical, intermediate, advanced)
+
+## Quick Start
+
+**New to Release Controller?**
+1. Start with the [Overview](OVERVIEW.md) to understand what Release Controller is
+2. Follow the [Setup Guide](SETUP.md) to get your environment ready
+3. Try the [Usage Guide](USAGE.md) to learn how to use Release Controller
+
+**Want to contribute?**
+1. Read the [Contributing Guide](CONTRIBUTING_GUIDE.md)
+2. Follow the [Onboarding Guide](ONBOARDING.md) to understand the codebase
+3. Find a good first issue and start contributing!
+
+**Looking for specific information?**
+- Check the [FAQ](FAQ.md) for common questions
+- Browse the [Architecture](ARCHITECTURE.md) docs for system design
+- Review the [Codebase Walkthrough](CODEBASE_WALKTHROUGH.md) for code structure
+
+## Documentation Structure
+
+```
+docs/
+├── README.md # This file
+├── OVERVIEW.md # High-level overview
+├── ARCHITECTURE.md # System architecture and diagrams
+├── CODEBASE_WALKTHROUGH.md # Code structure and components
+├── SETUP.md # Development environment setup
+├── USAGE.md # Usage examples and guides
+├── CONTRIBUTING_GUIDE.md # Contribution guidelines
+├── ONBOARDING.md # New contributor guide
+├── FAQ.md # Frequently asked questions
+└── SUMMARIES.md # Technical summaries
+```
+
+## External Resources
+
+- [OpenShift Release Repository](https://github.com/openshift/release/tree/master/core-services/release-controller) - Canonical documentation
+- [OpenShift CI Documentation](https://docs.ci.openshift.org/) - OpenShift CI documentation
+- [Prow Documentation](https://docs.prow.k8s.io/) - Prow CI system documentation
+
+## Getting Help
+
+- **Documentation**: Browse the docs in this directory
+- **GitHub Issues**: Search existing issues or create new ones
+- **Slack**: #forum-testplatform (for OpenShift team members)
+- **Pull Requests**: Ask questions in PR comments
+
+## Contributing to Documentation
+
+Documentation improvements are always welcome! To contribute:
+
+1. Make your changes to the relevant documentation file
+2. Test that links work and formatting is correct
+3. Create a Pull Request with your changes
+4. Reference any related issues
+
+See the [Contributing Guide](CONTRIBUTING_GUIDE.md) for more details.
+
+## Documentation Standards
+
+- Use Markdown format
+- Include code examples where helpful
+- Add diagrams using Mermaid syntax
+- Keep language clear and beginner-friendly
+- Update related docs when making changes
+
+## License
+
+This documentation is part of the Release Controller project and is licensed under the Apache-2.0 license.
+
diff --git a/docs/SETUP.md b/docs/SETUP.md
new file mode 100644
index 000000000..c5e790a24
--- /dev/null
+++ b/docs/SETUP.md
@@ -0,0 +1,406 @@
+# Setup Guide (Beginner Friendly)
+
+This guide will help you set up a development environment for working with Release Controller.
+
+## Prerequisites
+
+### Required Software
+
+1. **Go** (version 1.23.2 or later)
+ ```bash
+ # Check your Go version
+ go version
+
+ # If not installed, download from https://golang.org/dl/
+ ```
+
+2. **Git**
+ ```bash
+ git --version
+ ```
+
+3. **Make**
+ ```bash
+ make --version
+ ```
+
+4. **kubectl** (for interacting with Kubernetes)
+ ```bash
+ kubectl version --client
+ ```
+
+5. **oc** (OpenShift CLI) - Recommended
+ ```bash
+ oc version
+ ```
+
+### Optional but Recommended
+
+- **Docker** - For building container images
+- **kind** or **minikube** - For local Kubernetes cluster
+- **jq** - For JSON processing
+- **yq** - For YAML processing
+
+## Installation Steps
+
+### 1. Clone the Repository
+
+```bash
+# Clone the repository
+git clone https://github.com/openshift/release-controller.git
+cd release-controller
+
+# If you plan to contribute, fork first and clone your fork
+```
+
+### 2. Set Up Go Environment
+
+```bash
+# Set Go environment variables (if not already set)
+export GOPATH=$HOME/go
+export PATH=$PATH:$GOPATH/bin
+
+# Verify Go is working
+go env
+```
+
+### 3. Install Dependencies
+
+```bash
+# Download dependencies
+go mod download
+
+# Verify dependencies
+go mod verify
+
+# Vendor dependencies (if needed)
+make vendor
+```
+
+### 4. Build the Components
+
+```bash
+# Build all components
+make build
+
+# Or build specific component
+go build ./cmd/release-controller
+go build ./cmd/release-controller-api
+go build ./cmd/release-payload-controller
+go build ./cmd/release-reimport-controller
+```
+
+### 5. Verify Installation
+
+```bash
+# Check that components are built
+ls -la release-controller*
+./release-controller --help
+```
+
+## Environment Requirements
+
+### Development Environment
+
+- **Operating System**: Linux or macOS (Windows with WSL2)
+- **Memory**: Minimum 8GB RAM (16GB recommended)
+- **Disk Space**: At least 10GB free space
+- **Network**: Internet connection for downloading dependencies
+
+### For Testing with OpenShift
+
+- Access to an OpenShift cluster (or use CodeReady Containers)
+- Valid kubeconfig file
+- Appropriate cluster permissions
+- Access to ImageStreams in release namespaces
+
+### For Integration Testing
+
+- Access to `api.ci` OpenShift cluster (for OpenShift team members)
+- Release namespace access
+- ImageStream read/write permissions
+
+## How to Run the Project
+
+### Running Release Controller
+
+```bash
+# Basic usage with dry-run
+./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --dry-run \
+ -v=4
+
+# With kubeconfig
+./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --releases-kubeconfig ~/.kube/config \
+ --dry-run
+
+# Production-like (requires cluster access)
+./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --releases-kubeconfig ~/.kube/config \
+ --prow-job-kubeconfig ~/.kube/config
+```
+
+### Running Release Controller API
+
+```bash
+# Start API server
+./release-controller-api \
+ --release-namespace ocp \
+ --releases-kubeconfig ~/.kube/config
+
+# Access at http://localhost:8080
+```
+
+### Running Release Payload Controller
+
+```bash
+# Run payload controller
+./release-payload-controller \
+ --kubeconfig ~/.kube/config
+```
+
+### Running Release Reimport Controller
+
+```bash
+# Run reimport controller
+./release-reimport-controller \
+ --kubeconfig ~/.kube/config
+```
+
+### Running Tests
+
+```bash
+# Run all unit tests
+go test ./...
+
+# Run specific package tests
+go test ./pkg/release-controller/...
+
+# Run with verbose output
+go test -v ./pkg/release-controller/...
+
+# Run with coverage
+go test -cover ./pkg/...
+```
+
+## How to Test It
+
+### Unit Testing
+
+```bash
+# Run all unit tests
+go test ./...
+
+# Run tests for specific package
+go test ./pkg/release-controller/...
+
+# Run tests with coverage
+go test -cover ./pkg/...
+
+# Generate coverage report
+go test -coverprofile=coverage.out ./pkg/...
+go tool cover -html=coverage.out
+```
+
+### Manual Testing
+
+1. **Test Release Controller Locally:**
+ ```bash
+ # Run with dry-run mode
+ ./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --dry-run \
+ -v=4
+ ```
+
+2. **Test API Server:**
+ ```bash
+ # Start API server
+ ./release-controller-api \
+ --release-namespace ocp \
+ --releases-kubeconfig ~/.kube/config
+
+ # Access web UI
+ # Navigate to http://localhost:8080
+ ```
+
+3. **Test Configuration:**
+ ```bash
+ # Validate release configuration
+ # (Check release configs in openshift/release repository)
+ ```
+
+## Common Errors and Solutions
+
+### Error: "go: cannot find module"
+
+**Solution:**
+```bash
+# Ensure you're in the repository root
+cd /path/to/release-controller
+
+# Download dependencies
+go mod download
+
+# Or update dependencies
+go mod tidy
+```
+
+### Error: "command not found: release-controller"
+
+**Solution:**
+```bash
+# Build the component
+go build ./cmd/release-controller
+
+# Or use make
+make build
+```
+
+### Error: "permission denied" when accessing cluster
+
+**Solution:**
+```bash
+# Check kubeconfig
+kubectl config current-context
+
+# Verify cluster access
+kubectl get nodes
+
+# Check ImageStream access
+oc get imagestreams -n ocp
+```
+
+### Error: "cannot load package" or import errors
+
+**Solution:**
+```bash
+# Clean module cache
+go clean -modcache
+
+# Re-download dependencies
+go mod download
+
+# Verify go.mod is correct
+go mod verify
+```
+
+### Error: "ImageStream not found"
+
+**Solution:**
+- Verify you're using the correct namespace
+- Check ImageStream exists: `oc get imagestreams -n `
+- Verify you have read permissions
+
+### Error: "ReleasePayload CRD not found"
+
+**Solution:**
+```bash
+# Install CRDs
+make update-crd
+
+# Or apply manually
+kubectl apply -f artifacts/release.openshift.io_releasepayloads.yaml
+```
+
+### Error: Build failures due to missing dependencies
+
+**Solution:**
+```bash
+# Update dependencies
+go mod tidy
+go mod vendor
+```
+
+## Development Workflow
+
+### 1. Make Changes
+
+```bash
+# Create a feature branch
+git checkout -b feature/my-feature
+
+# Make your changes
+# ...
+
+# Format code
+go fmt ./...
+
+# Run tests
+go test ./...
+```
+
+### 2. Verify Changes
+
+```bash
+# Run tests
+go test ./...
+
+# Build components
+make build
+
+# Verify code generation (if changed APIs)
+make verify-codegen
+```
+
+### 3. Commit Changes
+
+```bash
+# Stage changes
+git add .
+
+# Commit with descriptive message
+git commit -m "Add feature: description of changes"
+
+# Push to your fork
+git push origin feature/my-feature
+```
+
+## IDE Setup
+
+### VS Code
+
+Recommended extensions:
+- Go extension
+- YAML extension
+- Kubernetes extension
+
+Settings:
+```json
+{
+ "go.useLanguageServer": true,
+ "go.formatTool": "goimports",
+ "editor.formatOnSave": true
+}
+```
+
+### GoLand / IntelliJ
+
+- Install Go plugin
+- Configure Go SDK
+- Enable goimports on save
+
+## Next Steps
+
+After setting up your environment:
+
+1. Read the [Usage Guide](USAGE.md) to learn how to use release controller
+2. Explore the [Codebase Walkthrough](CODEBASE_WALKTHROUGH.md) to understand the structure
+3. Check the [Contributing Guide](CONTRIBUTING_GUIDE.md) if you want to contribute
+4. Review the [Onboarding Guide](ONBOARDING.md) for deep dive
+
+## Getting Help
+
+- Check existing documentation
+- Search existing issues on GitHub
+- Ask in #forum-testplatform on Slack (for OpenShift team members)
+- Create a new issue with detailed error information
+
diff --git a/docs/SUMMARIES.md b/docs/SUMMARIES.md
new file mode 100644
index 000000000..bbd0178c2
--- /dev/null
+++ b/docs/SUMMARIES.md
@@ -0,0 +1,243 @@
+# Summaries
+
+This document provides summaries at different technical levels for different audiences.
+
+## Non-Technical Summary
+
+**What is Release Controller?**
+
+Release Controller is a software system that automatically creates, tests, and publishes new versions of OpenShift. Think of it as an automated assembly line for software releases.
+
+**What does it do?**
+
+When developers build new versions of OpenShift components, Release Controller automatically:
+- Collects all the necessary pieces (container images)
+- Assembles them into a complete release
+- Tests the release to make sure it works
+- Publishes the release so users can install it
+- Tracks the release status and any issues
+
+**Why is it important?**
+
+OpenShift releases contain hundreds of components that must work together perfectly. Without Release Controller, creating and managing releases would be extremely time-consuming, error-prone, and inconsistent. Release Controller automates this entire process, ensuring releases are created reliably and consistently.
+
+**Who uses it?**
+
+Primarily the OpenShift Release Engineering team and the Test Platform team. It runs automatically in the background, creating and managing releases for the OpenShift project.
+
+**Key Benefits:**
+- Saves time by automating repetitive tasks
+- Reduces errors through consistent processes
+- Enables faster release cycles
+- Provides visibility into release status
+- Ensures releases are tested before publication
+
+## Intermediate Summary
+
+**What is Release Controller?**
+
+Release Controller is a Kubernetes-based system that automates the creation, verification, and management of OpenShift release payloads. It monitors image streams, creates release images, runs verification tests, and publishes release information.
+
+**Core Components:**
+
+1. **Release Controller**: The main orchestrator that monitors ImageStreams, creates releases, manages verification, and publishes releases. It uses Kubernetes Jobs for release operations and ProwJobs for verification.
+
+2. **Release Controller API**: Provides a web interface and REST API for viewing releases, comparing versions, viewing changelogs, and visualizing upgrade graphs.
+
+3. **Release Payload Controller**: Manages ReleasePayload Custom Resources that track release state, including creation progress, verification status, and acceptance/rejection.
+
+4. **Release Reimport Controller**: Handles re-importing ImageStreamTags that failed initial import, ensuring all required images are available.
+
+**How it Works:**
+
+1. ART (Automated Release Tooling) builds images and updates ImageStreams
+2. Release Controller monitors ImageStreams for changes
+3. When new images are available, Release Controller creates a ReleasePayload
+4. A creation job is launched to assemble the release image
+5. Verification jobs (ProwJobs) are launched to test the release
+6. Results are tracked in the ReleasePayload status
+7. When all verifications pass, the release is published
+8. The release is made available in the container registry
+
+**Key Features:**
+
+- **Automated Release Creation**: Monitors ImageStreams and creates releases automatically
+- **Verification System**: Tests releases through ProwJobs before publication
+- **Release Payload Tracking**: Uses Custom Resources to track release state
+- **Image Mirroring**: Creates point-in-time snapshots of images
+- **Upgrade Graph Management**: Tracks and validates upgrade paths
+- **Garbage Collection**: Automatically removes old releases
+- **Auditing and Signing**: Audits and signs releases for security
+- **Web Interface**: Provides UI for browsing and managing releases
+
+**Technology Stack:**
+
+- Go for all components
+- Kubernetes/OpenShift for orchestration
+- ImageStreams for image management
+- Prow for verification jobs
+- Custom Resources (ReleasePayload) for state tracking
+
+**Use Cases:**
+
+- Creating OpenShift releases
+- Verifying release quality
+- Publishing releases to users
+- Managing release lifecycle
+- Tracking release status
+- Managing upgrade paths
+
+## Advanced Summary
+
+**What is Release Controller?**
+
+Release Controller is a comprehensive Kubernetes-native system implementing automated release payload creation, verification, and management for OpenShift. It uses Custom Resources (ReleasePayloads), ImageStreams, and Kubernetes Jobs to orchestrate the entire release lifecycle.
+
+**Architecture:**
+
+The system follows a controller-based architecture where multiple controllers work together:
+- **Release Controller**: Main orchestrator using informers to watch ImageStreams
+- **Release Payload Controller**: Manages ReleasePayload CRDs with multiple sub-controllers
+- **Release Reimport Controller**: Handles failed image imports
+- **API Server**: Provides web UI and REST API
+
+**Core Design Patterns:**
+
+1. **Controller Pattern**: All components implement the Kubernetes controller pattern:
+ ```go
+ type Controller interface {
+ Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error)
+ }
+ ```
+ - Watch resources via informers
+ - Reconcile desired state
+ - Handle errors with exponential backoff
+ - Update resource status
+
+2. **Custom Resources**: ReleasePayload CRD tracks release state:
+ ```go
+ type ReleasePayload struct {
+ Spec ReleasePayloadSpec // Release configuration
+ Status ReleasePayloadStatus // Execution state
+ }
+ ```
+ - Status contains conditions for different states
+ - Controllers update conditions based on operations
+ - Acceptance/rejection based on conditions
+
+3. **ImageStream-Based**: Uses OpenShift ImageStreams:
+ - Source ImageStreams contain built images
+ - Release ImageStreams contain release images
+ - Mirroring creates point-in-time snapshots
+ - Tags represent releases
+
+4. **Job-Based Execution**: Release operations execute as Kubernetes Jobs:
+ - Creation jobs assemble releases
+ - Mirror jobs copy images
+ - Verification jobs test releases
+ - Jobs are independent and retryable
+
+5. **Sync Pattern**: Main controller uses orchestrated sync functions:
+ ```go
+ func (c *Controller) sync() error {
+ if err := c.syncReleases(); err != nil { return err }
+ if err := c.syncReleasePayloads(); err != nil { return err }
+ if err := c.syncVerification(); err != nil { return err }
+ return nil
+ }
+ ```
+
+**Key Technical Components:**
+
+1. **Release Controller** (`cmd/release-controller/`):
+ - ImageStream monitoring via informers
+ - ReleasePayload creation and management
+ - Job creation and monitoring
+ - ProwJob integration for verification
+ - Image mirroring logic
+ - Upgrade graph management
+ - Garbage collection
+ - Audit and signing
+
+2. **Release Payload Controller** (`pkg/cmd/release-payload-controller/`):
+ - Multiple sub-controllers for different aspects
+ - Payload creation tracking
+ - Verification job monitoring
+ - Acceptance/rejection logic
+ - Status condition management
+
+3. **API Server** (`cmd/release-controller-api/`):
+ - HTTP server with route handlers
+ - Release information endpoints
+ - Changelog generation
+ - Release comparison
+ - Upgrade graph visualization
+ - Static web assets
+
+4. **ReleasePayload CRD** (`pkg/apis/release/v1alpha1/`):
+ - Custom resource definition
+ - Status conditions
+ - Verification tracking
+ - Acceptance criteria
+
+**Advanced Features:**
+
+1. **Multi-Architecture Support**: Handles releases for different architectures
+2. **Point-in-Time Snapshots**: Image mirroring creates consistent release images
+3. **Verification System**: Comprehensive testing through ProwJobs
+4. **Upgrade Graph**: Tracks and validates upgrade paths
+5. **Garbage Collection**: Automatic cleanup of old releases
+6. **Audit Trail**: Complete audit logging of release operations
+7. **Release Signing**: Cryptographic signing of releases
+8. **Jira Integration**: Automatic issue tracking and updates
+
+**Scalability Considerations:**
+
+- **Horizontal Scaling**: Controllers can be scaled horizontally
+- **Job Parallelization**: Multiple release jobs can run concurrently
+- **Caching**: ImageStream informers cache resource state
+- **Resource Management**: Garbage collection manages old releases
+- **Efficient API Usage**: Informers and watches for Kubernetes API
+
+**Integration Points:**
+
+- **ImageStreams**: Source and release image management
+- **Kubernetes Jobs**: Release operation execution
+- **ProwJobs**: Verification job execution
+- **Container Registry**: Release image publishing
+- **GCS**: Audit log storage
+- **Jira**: Issue tracking and updates
+
+**Extension Mechanisms:**
+
+1. **Custom Controllers**: Add to controller manager
+2. **Custom Sync Functions**: Add to sync.go
+3. **Custom API Endpoints**: Add to API server
+4. **Custom Verification**: Extend verification logic
+
+**Performance Optimizations:**
+
+- Informer-based resource watching
+- Efficient ImageStream queries
+- Parallel job execution
+- Resource cleanup via garbage collection
+- Caching of release information
+
+**Security Model:**
+
+- RBAC for Kubernetes resource access
+- ImageStream permissions for image access
+- Release signing for authenticity
+- Audit logging for traceability
+- Verification for release quality
+
+**Monitoring and Observability:**
+
+- Prometheus metrics for all components
+- Structured logging with klog
+- ReleasePayload status for state tracking
+- Web UI for release visibility
+- Audit logs for operations
+
+This architecture enables Release Controller to handle the complexity of OpenShift releases while ensuring consistency, reliability, and traceability.
+
diff --git a/docs/USAGE.md b/docs/USAGE.md
new file mode 100644
index 000000000..39e806615
--- /dev/null
+++ b/docs/USAGE.md
@@ -0,0 +1,292 @@
+# Usage Guide
+
+This guide provides practical examples and step-by-step instructions for using Release Controller.
+
+## Table of Contents
+
+- [Release Controller](#release-controller)
+- [Release Controller API](#release-controller-api)
+- [Release Payload Controller](#release-payload-controller)
+- [Configuration](#configuration)
+- [Common Workflows](#common-workflows)
+
+## Release Controller
+
+### Basic Usage
+
+```bash
+# Dry-run mode (recommended for testing)
+./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --dry-run \
+ -v=4
+
+# Production mode
+./release-controller \
+ --release-namespace ocp \
+ --job-namespace ci-release \
+ --releases-kubeconfig ~/.kube/config \
+ --prow-job-kubeconfig ~/.kube/config
+```
+
+### Common Options
+
+```bash
+./release-controller \
+ --release-namespace ocp \ # Namespace for releases
+ --publish-namespace ocp \ # Namespace for publishing
+ --job-namespace ci-release \ # Namespace for jobs
+ --prow-namespace ci \ # Prow namespace
+ --releases-kubeconfig ~/.kube/config \ # Kubeconfig for releases
+ --prow-job-kubeconfig ~/.kube/config \ # Kubeconfig for Prow jobs
+ --listen-addr :8080 \ # Listen address
+ --artifacts-host artifacts.example.com \ # Artifacts host
+ --dry-run \ # Dry-run mode
+ -v=4 # Verbosity level
+```
+
+### Advanced Options
+
+```bash
+./release-controller \
+ --audit-storage gs://bucket/audit \ # Audit storage location
+ --signing-keyring /path/to/keyring \ # Signing keyring
+ --verify-jira \ # Verify Jira integration
+ --soft-delete-release-tags \ # Soft delete tags
+ --release-architecture amd64 # Release architecture
+```
+
+## Release Controller API
+
+### Starting the API Server
+
+```bash
+# Basic usage
+./release-controller-api \
+ --release-namespace ocp \
+ --releases-kubeconfig ~/.kube/config
+
+# With custom port
+./release-controller-api \
+ --release-namespace ocp \
+ --releases-kubeconfig ~/.kube/config \
+ --listen-addr :9090
+```
+
+### Accessing the Web UI
+
+```bash
+# Start API server
+./release-controller-api --release-namespace ocp
+
+# Access web UI
+# Navigate to http://localhost:8080
+```
+
+### API Endpoints
+
+- `GET /` - Main dashboard
+- `GET /releases` - List all releases
+- `GET /release/{tag}` - Get release details
+- `GET /changelog?from={tag}&to={tag}` - Get changelog
+- `GET /compare?from={tag}&to={tag}` - Compare releases
+- `GET /upgrade-graph` - View upgrade graph
+
+### Example API Usage
+
+```bash
+# Get release list
+curl http://localhost:8080/releases
+
+# Get specific release
+curl http://localhost:8080/release/4.15.0-rc.0
+
+# Get changelog
+curl "http://localhost:8080/changelog?from=4.14.0&to=4.15.0"
+
+# Compare releases
+curl "http://localhost:8080/compare?from=4.14.0&to=4.15.0"
+```
+
+## Release Payload Controller
+
+### Running the Controller
+
+```bash
+# Basic usage
+./release-payload-controller \
+ --kubeconfig ~/.kube/config
+
+# With namespace
+./release-payload-controller \
+ --kubeconfig ~/.kube/config \
+ --namespace ocp
+```
+
+## Configuration
+
+### Release Configuration
+
+Release configurations are stored in the `openshift/release` repository at:
+`core-services/release-controller/_releases/{release-name}.json`
+
+Example configuration:
+```json
+{
+ "name": "4.15",
+ "to": "release",
+ "message": "OpenShift 4.15",
+ "mirrorPrefix": "quay.io/openshift-release-dev/ocp-release",
+ "check": {
+ "bugs": {
+ "enabled": true
+ },
+ "upgrade": {
+ "enabled": true
+ }
+ },
+ "verify": {
+ "prow": {
+ "enabled": true
+ }
+ },
+ "publish": {
+ "quay": {
+ "enabled": true
+ }
+ }
+}
+```
+
+### Environment Variables
+
+Common environment variables:
+- `KUBECONFIG` - Kubernetes config file path
+- `RELEASE_NAMESPACE` - Default release namespace
+- `JOB_NAMESPACE` - Default job namespace
+- `ARTIFACTS_HOST` - Artifacts host URL
+
+## Common Workflows
+
+### Example 1: Creating a Release
+
+1. **Ensure ImageStreams are updated:**
+ ```bash
+ oc get imagestream 4.15-art-latest -n ocp
+ ```
+
+2. **Release Controller detects changes:**
+ - Controller monitors ImageStreams
+ - Detects new images
+ - Creates ReleasePayload
+
+3. **Release is created:**
+ - Creation job launched
+ - Release image assembled
+ - ReleasePayload status updated
+
+4. **Verification runs:**
+ - ProwJobs launched
+ - Tests execute
+ - Results collected
+
+5. **Release published:**
+ - Release accepted
+ - Published to registry
+ - Made available
+
+### Example 2: Viewing Releases
+
+```bash
+# Via Web UI
+# Navigate to http://localhost:8080
+
+# Via API
+curl http://localhost:8080/releases
+
+# Via kubectl
+kubectl get releasepayloads -n ocp
+```
+
+### Example 3: Checking Release Status
+
+```bash
+# Get ReleasePayload
+kubectl get releasepayload 4.15.0-rc.0 -n ocp -o yaml
+
+# Check conditions
+kubectl get releasepayload 4.15.0-rc.0 -n ocp \
+ -o jsonpath='{.status.conditions}'
+
+# Check verification jobs
+kubectl get prowjobs -n ci-release \
+ -l release.openshift.io/release=4.15.0-rc.0
+```
+
+### Example 4: Troubleshooting a Release
+
+```bash
+# Check ReleasePayload status
+kubectl describe releasepayload 4.15.0-rc.0 -n ocp
+
+# Check creation job
+kubectl get jobs -n ci-release \
+ -l release.openshift.io/release=4.15.0-rc.0
+
+# Check job logs
+kubectl logs -n ci-release job/
+
+# Check verification jobs
+kubectl get prowjobs -n ci-release \
+ -l release.openshift.io/release=4.15.0-rc.0
+```
+
+## Best Practices
+
+1. **Always use `--dry-run` first** when testing
+2. **Test locally** before deploying
+3. **Monitor ReleasePayload status** for issues
+4. **Check logs** regularly for errors
+5. **Verify ImageStreams** before expecting releases
+6. **Use proper namespaces** for different environments
+7. **Monitor verification jobs** for failures
+
+## Troubleshooting
+
+### Release Not Created
+
+- Check ImageStream exists and is updated
+- Verify release configuration is correct
+- Check controller logs for errors
+- Verify namespace permissions
+
+### Verification Jobs Failing
+
+- Check ProwJob status
+- Review job logs
+- Verify test configurations
+- Check cluster resources
+
+### Release Not Published
+
+- Check ReleasePayload acceptance conditions
+- Verify all verification jobs passed
+- Check publish configuration
+- Review controller logs
+
+### API Not Responding
+
+- Check API server is running
+- Verify kubeconfig is correct
+- Check network connectivity
+- Review API server logs
+
+## Getting Help
+
+- Check component help: `./release-controller --help`
+- Review logs with `-v=4` for debug output
+- Check [FAQ](FAQ.md) for common issues
+- Search GitHub issues
+- Ask in #forum-testplatform on Slack
+