Skip to content

Documentation Map

Quick reference for finding documentation across the three repositories in the SyRF project.

Overview

The SyRF documentation is distributed across three repositories, all located in /home/chris/workspace/syrf/:

  • syrf/ - Application code, architecture, features, and development guides
  • cluster-gitops/ - Deployment operations and GitOps workflows
  • camarades-infrastructure/ - Infrastructure operations and Terraform

All three repositories are visible in a single workspace for LLM context.

By Topic

Topic Location Repository
Application Architecture syrf/docs/architecture/ syrf
Architecture Decisions (ADRs) syrf/docs/decisions/ syrf
Feature Planning syrf/docs/features/ syrf
How-To Guides (Development) syrf/docs/how-to/ syrf
Planning & Sprints syrf/docs/planning/ syrf
External Sources syrf/docs/sources/ syrf
Service Documentation syrf/src/services/{service}/README.md syrf
Helm Charts syrf/src/services/{service}/charts/ syrf
User Guide syrf/user-guide/ syrf
Deployment Operations cluster-gitops/docs/ cluster-gitops
ArgoCD Configuration cluster-gitops/apps/ cluster-gitops
Environment Values cluster-gitops/environments/ cluster-gitops
Infrastructure Operations camarades-infrastructure/docs/ camarades-infrastructure
Terraform Configuration camarades-infrastructure/terraform/ camarades-infrastructure
GKE Cluster camarades-infrastructure/terraform/main.tf camarades-infrastructure

By Action ("I Want To...")

I Want To... Look In...
Understand the system design syrf/docs/architecture/system-overview.md
Plan a new feature syrf/docs/README.md + Feature Planning Workflow
Start a Q&A session for planning syrf/docs/planning/templates/qa-template.md
Make an architectural decision syrf/docs/decisions/ (create new ADR)
Understand service dependencies syrf/docs/architecture/dependency-map.md
Deploy a service to staging cluster-gitops/docs/deploying-services.md
Promote to production cluster-gitops/docs/promotion-workflow.md
Change cluster infrastructure camarades-infrastructure/docs/terraform-guide.md
Modify GKE cluster settings camarades-infrastructure/docs/cluster-config.md
Run a service locally syrf/src/services/{service}/README.md
Configure Helm values syrf/src/services/{service}/charts/{chart}/values.yaml
Test CI/CD workflow syrf/docs/how-to/test-ci-cd-workflow.md
Set up required secrets syrf/docs/how-to/required-secrets.md
Use PR preview environments syrf/docs/how-to/use-pr-preview-environments.md
Understand GitOps architecture syrf/docs/architecture/gitops-architecture.md
Drop external research syrf/docs/sources/ (temporary staging area)

By Audience

Audience Primary Documentation Key Files
New Developer syrf/CLAUDE.md
syrf/README.md
syrf/docs/README.md		 Documentation framework guide
Project overview
Developer context
Feature Planner syrf/docs/features/
syrf/docs/how-to/feature-planning-workflow.md
syrf/docs/planning/templates/qa-template.md		 Feature briefs
Planning workflow
Q&A template
Backend Developer syrf/src/services/api/
syrf/src/services/project-management/
syrf/src/services/quartz/		 API service
PM service
Background jobs
Frontend Developer syrf/src/services/web/
syrf/src/services/web/README.md		 Angular app
Service docs
DevOps Engineer cluster-gitops/docs/
camarades-infrastructure/docs/		 Deployment guides
Infrastructure guides
Infrastructure Admin camarades-infrastructure/docs/terraform-guide.md
camarades-infrastructure/terraform/		 Terraform guide
IaC configs
LLM Assistant (Claude) syrf/CLAUDE.md
syrf/docs/architecture/llm-navigation-guide.md		 LLM context
Navigation guide
End User syrf/user-guide/
https://help.syrf.org.uk		 User documentation
Published site

By Document Type

Architecture & Reference

Architecture Decisions (ADRs)

How-To Guides

Development:

Deployment:

Configuration:

Infrastructure:

Planning & Templates

Features

Note: Features folder is currently empty - this will be populated as features are planned and implemented using the feature planning workflow.

By Repository

syrf/ (Main Repository)

Key Files:

  • CLAUDE.md - LLM context and developer guide
  • README.md - Project overview
  • docs/README.md - Documentation framework guide
  • docs/team.md - Team structure and workflow practices

Documentation Sections:

  • docs/architecture/ - System design and reference documentation
  • docs/decisions/ - Architecture Decision Records (ADRs)
  • docs/features/ - Feature briefs and technical plans
  • docs/how-to/ - Step-by-step guides
  • docs/planning/ - Active planning and sprint work
  • docs/sources/ - External research staging area

Source Code:

  • src/services/ - All microservices (API, PM, Quartz, Web, S3-Notifier)
  • src/libs/ - Shared libraries (Kernel, Mongo, AppServices, etc.)
  • user-guide/ - End-user documentation (Jekyll, published to help.syrf.org.uk)

cluster-gitops/ (Nested Repository)

Key Areas:

  • docs/ - Deployment operations documentation
  • apps/ - ArgoCD Application manifests
  • applicationsets/ - ApplicationSet generators
  • environments/ - Staging and production configurations

Documentation:

  • Deploying services to cluster
  • Promotion workflow (staging → production)
  • ArgoCD configuration
  • Environment-specific values

camarades-infrastructure/ (Nested Repository)

Key Areas:

  • docs/ - Infrastructure operations documentation
  • terraform/ - Terraform IaC for GKE cluster

Documentation:

  • Terraform guide
  • GKE cluster configuration
  • Infrastructure setup and management

Quick Start Guides

For New Developers

  1. Read CLAUDE.md - Understand the project context
  2. Read README.md - Get project overview
  3. Read docs/README.md - Learn documentation framework
  4. Review dependency-map.md - Understand system architecture
  5. Set up local environment using service READMEs

For Feature Planning

  1. Drop external research in docs/sources/
  2. Use Q&A template for iterative refinement
  3. Follow feature-planning-workflow.md
  4. Create Feature Brief in docs/features/
  5. Create Technical Plan alongside Feature Brief

For Deployment

  1. Review GitOps architecture
  2. Read deploying-services.md
  3. Understand promotion-workflow.md
  4. Configure required secrets per required-secrets.md

For Infrastructure Changes

  1. Review cluster-config.md
  2. Read terraform-guide.md
  3. Make changes in Terraform
  4. Apply via Terraform workflow

Search Tips

# Find all documentation
Glob: **/docs/**/*.md

# Find specific topics
Grep: pattern="authentication" path="/home/chris/workspace/syrf"

# Find by document type
Grep: pattern='doc-type: "ADR"' path="/home/chris/workspace/syrf/docs"

# Find draft documents
Grep: pattern='status: "Draft"' path="/home/chris/workspace/syrf/docs"

The published documentation site (docs.syrf.org.uk) includes full-text search across all three repositories.

Last updated: 2025-11-21