# Homelab Monorepo

## Overview
Monorepo for frontend/backend apps deployed to a k3s cluster on Intel NUC machines.
GitOps via ArgoCD, bare-metal provisioning via Ansible, Turborepo for app builds.

## Tech Stack
- **Monorepo**: Turborepo + pnpm workspaces
- **Apps**: Next.js (frontend), Express (API), TypeScript
- **Infrastructure**: k3s, ArgoCD, Ansible
- **Platform**: Traefik, cert-manager, CloudNativePG, Valkey, Longhorn, Sealed Secrets
- **Observability**: kube-prometheus-stack, Loki, Promtail, Grafana
- **CI/CD**: GitHub Actions → ghcr.io → ArgoCD
- **Task Runner**: Taskfile (go-task)

## Directory Structure
- `apps/` — Deployable applications (each has src/, Dockerfile, k8s/ manifests)
- `packages/` — Shared libraries (ui, config-eslint, config-typescript, db)
- `infra/ansible/` — Bare-metal provisioning playbooks and roles
- `infra/kubernetes/` — K8s manifests (argocd, platform, observability, namespaces)
- `infra/ubiquiti/` — Network documentation for Ubiquiti Cloud Gateway
- `scripts/` — Utility scripts (new-app, seal-secret, kubeconfig-fetch)
- `templates/` — Copier templates for scaffolding new apps

## Conventions
- All apps use Kustomize with base + overlays (preview, production)
- K8s manifests live inside each app at `k8s/`
- Secrets are sealed with kubeseal before committing
- Branch deploys create `preview-<PR#>` namespaces automatically
- Use `task <command>` for all operations (see Taskfile.yaml)
- Docker images tagged with git SHA, pushed to ghcr.io

## Common Commands
```bash
task dev              # Start all apps in dev mode
task build            # Build all apps
task lint             # Lint everything
task cluster:bootstrap # Provision NUCs with Ansible
task cluster:kubeconfig # Fetch kubeconfig from server node
task platform:install  # Bootstrap ArgoCD + platform
task secrets:seal      # Seal a secret for git
```

## Testing
- Run `task test` for all tests
- Run `task lint` for linting (includes ansible-lint)
- K8s manifests: `kubectl apply --dry-run=client -f <file>`
- Kustomize: `kustomize build <dir>` to verify rendering