docs/architecture.md

# Architecture

## Overview

AstraCloud Developer Platform has four major layers:

1. Developer Experience Layer
2. CI/CD and DevSecOps Layer
3. GitOps and Kubernetes Platform Layer
4. Multi-Cloud Disaster Recovery Layer

## 1. Developer Experience Layer

Primary tool: **Backstage**

Backstage provides:

- Software catalog
- Service templates
- Documentation
- Links to GitHub, Argo CD, Grafana, SonarQube, and Jenkins
- Developer self-service workflows

## 2. CI/CD and DevSecOps Layer

Primary tools:

- GitHub Actions
- Jenkins
- SonarQube
- Trivy
- Gitleaks
- Harbor

Pipeline flow:

1. Developer pushes code.
2. GitHub Actions runs tests.
3. Gitleaks scans secrets.
4. SonarQube checks code quality.
5. Trivy scans image and IaC.
6. Docker image is built.
7. Image is pushed to Harbor.
8. GitOps repo is updated.
9. Argo CD deploys the new version.

## 3. GitOps and Kubernetes Platform Layer

Primary tools:

- K3s
- Helm
- Argo CD
- Kyverno
- Prometheus
- Grafana
- Loki
- Longhorn
- Velero

The home server is the main production cluster.

## 4. Multi-Cloud Disaster Recovery Layer

Primary tools:

- Terraform
- Ansible
- Velero
- Cloudflare

Temporary DR flow:

1. Jenkins starts DR job.
2. Terraform creates VM/network/firewall in AWS/Azure/GCP.
3. Ansible installs K3s.
4. Argo CD deploys platform apps.
5. Backup is restored.
6. DNS/tunnel is switched.
7. Demo is completed.
8. Terraform destroys cloud resources.

## Main Components

| Component | Tool |
|---|---|
| Portal | Backstage |
| Kubernetes | K3s |
| GitOps | Argo CD |
| Infrastructure | Terraform |
| Server setup | Ansible |
| CI | GitHub Actions |
| Operations automation | Jenkins |
| Registry | Harbor |
| Code quality | SonarQube |
| Vulnerability scan | Trivy |
| Secret scan | Gitleaks |
| Policy | Kyverno |
| Metrics | Prometheus |
| Dashboards | Grafana |
| Logs | Loki |
| Backup | Velero |
| Storage | Longhorn |
| Auth | Keycloak |
| Public access | Cloudflare Tunnel |