BMAD initial project scan documents

docs/architecture.md

@@ -0,0 +1,108 @@
+# Architecture
+
+## Overview
+
+concourse-shared is a CI/CD infrastructure repository that distributes shared CI tasks and GitHub Actions across multiple repositories in the blinkbitcoin organization.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    concourse-shared repo                         │
+├─────────────────────────────────────────────────────────────────┤
+│  shared/actions/     shared/ci/tasks/      images/              │
+│  (GH Actions)        (Concourse tasks)     (Dockerfiles)        │
+└──────────────┬──────────────────────────────────────────────────┘
+               │
+               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Concourse CI Pipeline                         │
+├─────────────────────────────────────────────────────────────────┤
+│  bump-shared-files-in-*  │  build-*-image  │  backup-org-to-gcp │
+└──────────────┬───────────┴────────┬────────┴────────────────────┘
+               │                    │
+               ▼                    ▼
+┌──────────────────────┐  ┌─────────────────────────────┐
+│   Target Repos (7)   │  │   us.gcr.io/galoy-org       │
+│   via vendir sync    │  │   Docker images (4)         │
+└──────────────────────┘  └─────────────────────────────┘
+```
+
+## Components
+
+### Pipeline Definition (`ci/pipeline.yml`)
+
+ytt-templated Concourse pipeline with three job groups:
+
+1. **bump-shared-files** - For each target repo:
+   - Clones concourse-shared
+   - Runs `bump-shared-files.sh` with repo's feature flags
+   - Uses vendir to sync appropriate files
+   - Creates PR in target repo
+
+2. **images** - Builds CI runner images:
+   - Uses Kaniko for in-cluster builds
+   - Pushes to Google Container Registry
+
+3. **backups** - Daily org backup:
+   - Clones all blinkbitcoin repos
+   - Compresses and uploads to GCS
+
+### Shared Tasks (`shared/ci/tasks/`)
+
+Reusable shell scripts for CI operations:
+
+| Script | Purpose |
+|--------|---------|
+| `nodejs-helpers.sh` | `unpack_deps()`, `check_code()` functions |
+| `nodejs-check-code.sh` | Runs pnpm/yarn code:check |
+| `nodejs-audit.sh` | Security audit with configurable level |
+| `rust-helpers.sh` | Cargo environment setup |
+| `rust-check-code.sh` | Runs `make check-code` in nix develop |
+| `prep-release-src.sh` | Generates changelog, bumps version |
+| `docker-prep-docker-build-env.sh` | Sets VERSION, COMMITHASH, BUILDTIME |
+| `chart-open-charts-pr.sh` | Creates PR to bump image in charts repo |
+
+### Pipeline Fragments (`shared/ci/pipeline-fragments.lib.yml`)
+
+ytt library providing reusable pipeline components:
+
+- Task image configs (`nodejs_task_image_config()`, `rust_task_image_config()`)
+- Job definitions (`nodejs_check_code()`, `rust_check_code()`, `build_edge_image()`)
+- Resource definitions (`repo_resource()`, `edge_image_resource()`)
+- Resource types (`gcs-resource`, `slack-notification`)
+
+### Docker Images (`images/`)
+
+| Image | Base | Key Tools |
+|-------|------|-----------|
+| nodejs-concourse | node:20-bookworm | pnpm, docker, gcloud, gh-cli, bats |
+| rust-concourse | rust:latest | cargo-nextest, clippy, sqlx-cli, docker |
+| release-pipeline | python:3.8-buster | git-cliff, helm, kubectl, bump2version |
+| wincross | rust:latest | mingw-w64, x86_64-pc-windows-gnu target |
+
+## Configuration
+
+### `ci/values.yml`
+
+Defines target repositories and their features:
+
+```yaml
+src_repos:
+  repo-name: ["nodejs"]           # Node.js only
+  repo-name: ["rust", "docker"]   # Rust with Docker
+  repo-name: ["nodejs", "docker", "chart"]  # Full stack
+```
+
+### `vendir.tmpl.yml`
+
+Controls file distribution via excludePaths:
+- Feature-prefixed files excluded by default
+- `bump-shared-files.sh` removes excludes for enabled features
+
+## Security
+
+- GitHub App authentication (`gh-token` for JWT generation)
+- GCP service account for GCS access
+- SSH keys for remote host execution
+- Docker registry credentials via Concourse secrets

docs/development-guide.md

@@ -0,0 +1,87 @@
+# Development Guide
+
+## Prerequisites
+
+- Nix with flakes enabled
+- direnv (optional, for automatic environment loading)
+- Access to blinkbitcoin GitHub org
+
+## Environment Setup
+
+```bash
+# Clone the repository
+gh repo clone blinkbitcoin/concourse-shared
+cd concourse-shared
+
+# Enter dev environment (provides ytt, alejandra)
+nix develop
+
+# Or with direnv (automatic)
+direnv allow
+```
+
+## Development Workflow
+
+### Adding a New Target Repository
+
+1. Edit `ci/values.yml`:
+   ```yaml
+   src_repos:
+     new-repo-name: ["nodejs"]  # or ["rust"], ["nodejs", "docker", "chart"], etc.
+   ```
+
+2. Push changes and run pipeline:
+   ```bash
+   ci/repipe
+   ```
+
+3. Ensure `galoybot` has repo permissions and `blinkbitcoinbot` label exists
+
+### Feature Flags
+
+| Flag | Description |
+|------|-------------|
+| `nodejs` | Syncs Node.js tasks (check-code, audit, helpers) |
+| `rust` | Syncs Rust tasks (check-code, helpers) |
+| `docker` | Syncs Docker build tasks |
+| `chart` | Syncs Helm chart tasks |
+
+Files without a feature prefix are synced to all repos.
+
+### Modifying Shared Tasks
+
+1. Edit files in `shared/ci/tasks/` or `shared/actions/`
+2. Commit and push to main
+3. Pipeline auto-triggers and creates PRs in all target repos
+
+### Building Docker Images
+
+Images auto-build when their Dockerfile changes:
+- `images/nodejs-concourse/Dockerfile` → `us.gcr.io/galoy-org/nodejs-concourse`
+- `images/rust-concourse/Dockerfile` → `us.gcr.io/galoy-org/rust-concourse`
+- `images/release/Dockerfile` → `us.gcr.io/galoy-org/release-pipeline`
+- `images/wincross/Dockerfile` → `us.gcr.io/galoy-org/wincross-rust`
+
+## Pipeline Structure
+
+### Pipeline Groups
+
+| Group | Jobs |
+|-------|------|
+| `bump-shared-files` | One job per target repo |
+| `images` | 4 image build jobs |
+| `backups` | Daily GitHub org backup |
+
+### Vendir Sync Process
+
+The `vendir.tmpl.yml` template controls file syncing:
+- `shared/actions/*` → `.github/workflows/vendor/`
+- `shared/ci/**/*` → `ci/vendor/`
+
+Feature-specific files are excluded via `excludePaths` and selectively included based on repo's feature flags.
+
+## Testing Changes
+
+No local test suite. Changes are validated by:
+1. Pipeline execution success
+2. Target repo CI passing after PR merge

docs/index.md

@@ -0,0 +1,40 @@
+# concourse-shared Documentation
+
+## Project Overview
+
+- **Type:** Monolith (CI/CD Infrastructure)
+- **Primary Language:** Shell (Bash)
+- **Architecture:** Pipeline-as-Code with shared task distribution
+
+## Quick Reference
+
+- **Tech Stack:** Concourse CI, ytt, Nix, Docker, GCP
+- **Entry Point:** `ci/pipeline.yml`
+- **Architecture Pattern:** Centralized CI resource distribution
+
+## Generated Documentation
+
+- [Project Overview](./project-overview.md)
+- [Architecture](./architecture.md)
+- [Source Tree Analysis](./source-tree-analysis.md)
+- [Development Guide](./development-guide.md)
+
+## Existing Documentation
+
+- [README](../README.md) - Original project documentation
+
+## Getting Started
+
+1. Clone: `gh repo clone blinkbitcoin/concourse-shared`
+2. Enter dev env: `nix develop`
+3. Add new repo: Edit `ci/values.yml`, run `ci/repipe`
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `ci/pipeline.yml` | Main Concourse pipeline |
+| `ci/values.yml` | Target repos and features |
+| `shared/ci/tasks/` | Shared CI scripts |
+| `shared/actions/` | GitHub Actions workflows |
+| `images/` | Docker image definitions |

docs/project-overview.md

@@ -0,0 +1,56 @@
+# Project Overview
+
+## concourse-shared
+
+Shared CI/CD resources for the blinkbitcoin GitHub organization.
+
+## Purpose
+
+Centralizes CI tasks, GitHub Actions, and Docker images to ensure consistency across multiple repositories. Changes made here automatically propagate to all target repos via Concourse CI pipelines.
+
+## Quick Reference
+
+| Attribute | Value |
+|-----------|-------|
+| **Type** | CI/CD Infrastructure |
+| **Platform** | Concourse CI |
+| **Language** | Shell (Bash), YAML |
+| **Templating** | ytt (Carvel) |
+| **Dev Environment** | Nix Flakes |
+| **Container Registry** | us.gcr.io/galoy-org |
+
+## Capabilities
+
+### Shared CI Tasks
+- Node.js: code checking, security audits, dependency caching (yarn/pnpm)
+- Rust: code checking, cargo configuration
+- Docker: build environment preparation, image digest bumping
+- Charts: Helm integration testing, chart PR automation
+- Release: changelog generation, semantic versioning
+
+### Docker Images
+- `nodejs-concourse` - Node.js 20 CI runner
+- `rust-concourse` - Rust CI runner
+- `release-pipeline` - Release automation
+- `wincross-rust` - Windows cross-compilation
+
+### Automation
+- Daily GitHub org backup to GCS
+- Auto-PR creation for shared file updates
+
+## Target Repositories
+
+| Repository | Features |
+|------------|----------|
+| mavapay-client | nodejs |
+| blink-client | nodejs |
+| blink-nostr | nodejs, docker, chart |
+| blink-fiat | nodejs, docker, chart |
+| blink-circles | nodejs |
+| blink-card | rust, docker, chart |
+| stablesats-rs | rust, docker, chart |
+
+## Links
+
+- [Pipeline](https://ci.blink.sv/teams/dev/pipelines/blink-concourse-shared)
+- [GitHub](https://github.com/blinkbitcoin/concourse-shared)

docs/project-scan-report.json

@@ -0,0 +1,49 @@
+{
+  "workflow_version": "1.2.0",
+  "timestamps": {
+    "started": "2025-12-09T20:45:00Z",
+    "last_updated": "2025-12-09T21:05:00Z",
+    "completed": "2025-12-09T21:05:00Z"
+  },
+  "mode": "initial_scan",
+  "scan_level": "exhaustive",
+  "project_root": "/Users/kim/src/concourse-shared",
+  "output_folder": "/Users/kim/src/concourse-shared/docs",
+  "completed_steps": [
+    {"step": "step_1", "status": "completed", "timestamp": "2025-12-09T20:45:00Z", "summary": "Classified as monolith with 1 part (infra type)"},
+    {"step": "step_2", "status": "completed", "timestamp": "2025-12-09T20:48:00Z", "summary": "Found 1 existing doc (README.md)"},
+    {"step": "step_3", "status": "completed", "timestamp": "2025-12-09T20:50:00Z", "summary": "Tech stack: Concourse CI, ytt, Shell, Docker, Nix"},
+    {"step": "step_4", "status": "completed", "timestamp": "2025-12-09T20:52:00Z", "summary": "CI/CD analysis: 3 pipeline groups, 7 target repos"},
+    {"step": "step_5", "status": "completed", "timestamp": "2025-12-09T20:56:00Z", "summary": "Source tree documented"},
+    {"step": "step_6", "status": "completed", "timestamp": "2025-12-09T20:59:00Z", "summary": "Dev guide written"},
+    {"step": "step_8", "status": "completed", "timestamp": "2025-12-09T21:02:00Z", "summary": "Architecture doc written"},
+    {"step": "step_9", "status": "completed", "timestamp": "2025-12-09T21:03:00Z", "summary": "Project overview written"},
+    {"step": "step_10", "status": "completed", "timestamp": "2025-12-09T21:03:00Z", "summary": "Master index generated"},
+    {"step": "step_11", "status": "completed", "timestamp": "2025-12-09T21:04:00Z", "summary": "Validation complete, no incomplete markers"},
+    {"step": "step_12", "status": "completed", "timestamp": "2025-12-09T21:05:00Z", "summary": "Workflow complete"}
+  ],
+  "current_step": "completed",
+  "project_types": [
+    {
+      "part_id": "main",
+      "project_type_id": "infra",
+      "display_name": "CI/CD Infrastructure"
+    }
+  ],
+  "findings": {
+    "project_classification": {
+      "repository_type": "monolith",
+      "parts_count": 1,
+      "primary_tech": "Concourse CI, Shell, Docker, Nix"
+    }
+  },
+  "outputs_generated": [
+    "project-scan-report.json",
+    "index.md",
+    "project-overview.md",
+    "architecture.md",
+    "source-tree-analysis.md",
+    "development-guide.md"
+  ],
+  "resume_instructions": "Workflow completed successfully"
+}