feat: Update documentation and golang dependencies (#146)

Signed-off-by: flacatus <flacatus@redhat.com>

Author: flacatus

README.md

@@ -1,162 +1,173 @@
 # DORA Metrics Server
 
-A professional Go Fiber server with a clean, minimal API focused on health monitoring.
+Automated collection and forwarding of DORA metrics data from ArgoCD deployments and WebRCA incidents to [Apache DevLake](https://devlake.apache.org/). Enables engineering teams to measure software delivery performance through the four key DORA metrics without manual data entry.
+
+## Overview
+
+```text
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│     ArgoCD      │     │  DORA Metrics   │     │  Apache DevLake │
+│   Deployments   │────▶│     Server      │────▶│   Dashboards    │
+└─────────────────┘     └────────┬────────┘     └─────────────────┘
+                                 │
+┌─────────────────┐              │
+│     WebRCA      │──────────────┘
+│    Incidents    │
+└─────────────────┘
+```
 
-## Features
+This server watches ArgoCD applications for deployment events, collects incident data from WebRCA, and forwards everything to DevLake via webhooks. DevLake then calculates and visualizes DORA metrics in Grafana dashboards.
 
-- 🚀 Built with [Go Fiber](https://gofiber.io/) - Fast HTTP framework
-- 🏥 Health check endpoint
-- 🔍 WebRCA incident monitoring (checks OpenShift WebRCA API every 30 minutes)
-- 🔧 Environment-based configuration
-- 📝 Structured logging
-- 🌐 CORS support
-- 🛡️ Error handling middleware
-- 📁 Standard Go project layout
+## What are DORA Metrics?
 
-## Quick Start
+[DORA](https://dora.dev/) (DevOps Research and Assessment) metrics are industry-standard indicators for measuring software delivery performance:
 
-### Prerequisites
+| Metric | What It Measures | Data Source |
+|--------|------------------|-------------|
+| **Deployment Frequency** | How often you deploy to production | ArgoCD deployments |
+| **Lead Time for Changes** | Time from commit to production | Commit timestamps → Deployment time |
+| **Change Failure Rate** | Percentage of failed deployments | ArgoCD sync failures |
+| **Mean Time to Recovery** | Time to recover from incidents | WebRCA incidents |
 
-- Go 1.21 or higher
-- Git
+Learn more in [Apache DevLake's DORA documentation](https://devlake.apache.org/docs/DORA/).
 
-### Installation
+## How It Works
 
-1. Clone the repository:
-```bash
-git clone <repository-url>
-cd dora-metrics
-```
+### ArgoCD Integration
 
-2. Install dependencies:
-```bash
-go mod tidy
-```
+The server monitors ArgoCD applications across configured namespaces and:
 
-3. Copy environment file:
-```bash
-cp .env.example .env
-```
+1. **Detects deployments** when applications sync to new revisions
+2. **Extracts commit information** from container images with SHA-based tags
+3. **Retrieves commit metadata** from GitHub (author, message, timestamp)
+4. **Sends deployment events** to DevLake with full commit history
 
-4. Run the server:
-```bash
-go run .
-```
+### WebRCA Integration
 
-The server will start on `http://localhost:3000` by default.
+For incident tracking, the server:
 
-## API Endpoints
+1. **Polls WebRCA API** at configured intervals
+2. **Collects incident data** including creation time and resolution
+3. **Forwards incidents** to DevLake for MTTR calculation
 
-### Health Check
-```http
-GET /api/v1/health
-```
+### Team Routing
 
-Returns server health status, uptime, and version information.
+Deployments can be routed to multiple DevLake projects:
 
-### Root
-```http
-GET /
-```
+- **Global Project**: Receives all deployments for organization-wide visibility
+- **Team Projects**: Receive only deployments for specific components
 
-Returns basic server information and available endpoints.
+This enables both executive dashboards and team-specific metrics views.
 
-## Configuration
+## Quick Start
 
-The server can be configured using a YAML file (`configs/config.yaml`) with environment variable overrides:
+### Prerequisites
 
-### YAML Configuration
+- Go 1.21+
+- Redis (for deployment deduplication)
+- Access to ArgoCD cluster (for deployment monitoring)
+- DevLake instance with webhook configured
 
-Create `configs/config.yaml`:
+### Running Locally
 
-```yaml
-server:
-  port: "3000"
-  environment: "development"
-  log_level: "info"
+```bash
+# Clone and install dependencies
+git clone <repository-url>
+cd dora-metrics
+go mod tidy
 
-webrca:
-  enabled: true
-  api_url: "https://api.openshift.com/api/web-rca/v1/incidents"
-  interval: "30m"
-  # OCM token should be set via environment variable OCM_TOKEN for security
+# Set required environment variables
+export OFFLINE_TOKEN="your_ocm_offline_token"
+export DEVLAKE_WEBHOOK_TOKEN="your_devlake_token"
+
+# Run the server
+go run cmd/server/main.go
 ```
 
-### Environment Variables
+### Deploying to Kubernetes
 
-Environment variables override YAML settings:
+Kubernetes manifests are provided in `manifests/`:
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `PORT` | `3000` | Server port |
-| `ENVIRONMENT` | `development` | Environment (development/production) |
-| `LOG_LEVEL` | `info` | Log level |
-| `WEBRCA_ENABLED` | `true` | Enable WebRCA incident checking |
-| `WEBRCA_API_URL` | `https://api.openshift.com/api/web-rca/v1/incidents` | WebRCA API URL |
-| `WEBRCA_INTERVAL` | `30m` | WebRCA check interval |
-| `OCM_TOKEN` | `` | OCM token for WebRCA API authentication |
+```bash
+# For production
+kubectl apply -k manifests/production/
 
-## Project Structure
+# For local/staging
+kubectl apply -k manifests/local/
+```
 
-Following the [Go Standard Project Layout](https://github.com/golang-standards/project-layout):
+## Configuration
 
-```
-.
-├── cmd/
-│   └── server/
-│       └── main.go          # Application entry point
-├── internal/
-│   ├── config/
-│   │   └── config.go        # Configuration management
-│   ├── handlers/
-│   │   └── handlers.go      # HTTP handlers and routes
-│   └── server/
-│       └── server.go        # Server setup and configuration
-├── configs/
-│   └── config.yaml          # Application configuration
-├── go.mod                   # Go module definition
-├── Dockerfile               # Docker configuration
-└── README.md                # This file
-```
+Configuration is managed via YAML files with environment variable overrides.
 
-## Development
+### Key Configuration Areas
 
-### Running in Development
+| Area | Description |
+|------|-------------|
+| **ArgoCD** | Namespaces to watch, components to ignore, known clusters |
+| **WebRCA** | API endpoint, polling interval |
+| **DevLake** | Base URL, project IDs, team routing |
+| **Redis** | Connection settings for deployment caching |
 
-```bash
-# Set your offline token
-export OFFLINE_TOKEN="your_offline_token_here"
+### Environment Variables
 
-# Run the application
-go run cmd/server/main.go
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OFFLINE_TOKEN` | Yes | Red Hat OCM offline token for WebRCA API |
+| `DEVLAKE_WEBHOOK_TOKEN` | Yes | Authentication token for DevLake webhooks |
+| `REDIS_HOST` | No | Redis host (default: from config) |
+| `REDIS_PASSWORD` | No | Redis password |
+
+### Example Configuration
+
+```yaml
+argocd:
+  enabled: true
+  namespaces:
+    - konflux-public-production
+  components_to_ignore:
+    - monitoring
+    - openshift-gitops
+
+integration:
+  devlake:
+    enabled: true
+    base_url: "https://devlake.example.com"
+    project_id: "1"  # Global project
+    teams:
+      - name: "my-team"
+        project_id: "2"
+        argocd_components:
+          - my-service
+          - my-api
 ```
 
-### Building
+## Documentation
 
-```bash
-# Build the application
-go build -o bin/dora-metrics cmd/server/main.go
+| Document | Description |
+|----------|-------------|
+| [Configuration Guide](docs/configuration-sop.md) | Comprehensive configuration reference |
+| [Deployment Guide](docs/deployment-guide.md) | Kubernetes deployment instructions |
+| [Architecture](docs/architecture.md) | System design and data flow diagrams |
 
-# Run the binary
-./bin/dora-metrics
-```
+## API Endpoints
 
-### Running Tests
+| Endpoint | Description |
+|----------|-------------|
+| `GET /` | Server info and available endpoints |
+| `GET /api/v1/health` | Health check with uptime and version |
+
+## Development
 
 ```bash
+# Run tests
 go test ./...
-```
-
-## Docker Support
 
-To run with Docker:
+# Build binary
+go build -o bin/dora-metrics cmd/server/main.go
 
-```bash
-# Build the image
+# Build Docker image
 docker build -t dora-metrics .
-
-# Run the container
-docker run -p 3000:3000 dora-metrics
 ```
 
 ## Contributing
@@ -169,4 +180,4 @@ docker run -p 3000:3000 dora-metrics
 
 ## License
 
-This project is licensed under the MIT License - see the LICENSE file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.

docs/README.md

@@ -11,7 +11,6 @@ This directory contains comprehensive documentation for the DORA Metrics system
 | [**Architecture**](architecture.md) | Complete system architecture and design | Components, data flow, DORA metrics, configuration |
 | [**Data Flow**](data-flow.md) | Detailed data flow diagrams and processes | Event processing, commit handling, DevLake integration |
 | [**Deployment Guide**](deployment-guide.md) | Step-by-step deployment instructions | Kubernetes manifests, configuration, monitoring |
-| [**Configuration SOP**](configuration-sop.md) | Comprehensive configuration guide | All configuration options, team setup, troubleshooting |
 
 ## 🏗️ System Architecture