ROXY-SYSTEMS: Welcome to Enterprise Development

✅Prerequisites Check

You should have already:

Completed the COSMOS quick start (cosmos-welcome.roxy.systems)
Installed COSMOS v5.2+ (Membrane + Cloud Edition)
GitHub access to roxy-systems repository
Familiarity with c-commit, c-pulse, git push

If any of these are fuzzy, go back and complete cosmos-welcome first before proceeding.

🏗️Step 1: Clone & Initialize ROXY-SYSTEMS

Clone the repository:

cd ~/Code && git clone https://github.com/vepsservice07-stack/roxy-systems.git && cd roxy-systems

Run the installer:

./setup.sh

This script:

✅ Verifies COSMOS is installed (v2.2+)
✅ Detects your available language tools (Rust, Go, Node, Java, Python)
✅ Validates cosmos.json manifest structure
✅ Installs git hooks to enforce COSMOS usage
✅ Initializes development environment
✅ Membrane: Generates .cosmos-membrane.json for repo discovery
✅ Issues: Configures c-issue adapters (GitHub/Linear/Jira)
✅ Cloud: Preps c-cloud-setup for artifact registries

Expected output: All checks pass with green checkmarks (✅)

Verify setup worked:

c-pulse

You should see a real-time status table of all services. This is your "what's happening right now" dashboard.

📋Step 2: Understand cosmos.json

ROXY-SYSTEMS uses cosmos.json as the single source of truth for all service metadata:

cat cosmos.json | jq .

This manifest defines:

🏢 Workspace Name, description, and overall version of the monorepo

📦 Projects Each service: language, path, version, type, maintainers

🔧 Settings Version format, auto-detection, changelog generation

🌳 Structure Explicit project definitions overriding auto-detection

Key point: COSMOS scans for both manifest-defined projects AND auto-detected projects (with Cargo.toml, package.json, etc.). The manifest takes precedence when both exist.

💡 Insight: The manifest approach lets you version documentation and custom project types alongside code services. This is why COSMOS is called "manifest-aware."

📋Step 2.5: Cloud & Issue Configuration

Before contributing, configure your environment for the ecosystem.

1. Configure Issue Tracking:

c-issue interactive

Follow the prompts to link your GitHub/Linear account. This generates .cosmos.issue.env.

2. Configure Cloud Registry (First Time Only):

c-cloud-setup

This detects your provider (AWS/GCP/Azure) and configures where c-linker will push images.

🗂️Step 3: Explore the Directory Structure

See the full layout:

tree -L 2 -I 'node_modules|target|.git'

What you'll see:

roxy-systems/
├── cosmos.json                    (Manifest of all services)
├── docker/                        (Container definitions)
│   └── services/
│       ├── Dockerfile.signer-service
│       ├── Dockerfile.identity-service
│       └── ... (one per service)
├── kubernetes/                    (Orchestration configs)
│   ├── base/                      (Core manifests)
│   ├── overlays/                  (Environment-specific)
│   │   ├── dev/
│   │   ├── staging/
│   │   └── production/
│   └── monitoring/                (Observability)
├── deployment/                    (Release & rollback tools)
│   ├── deploy.sh
│   ├── validate.sh
│   ├── rollback.sh
│   └── config/
├── .github/workflows/             (CI/CD pipelines)
│   ├── build-base-images.yml      (Control Plane)
│   └── build-and-push.yml         (Application Plane)
├── src/                           (Application source code)
│   ├── roxy-identity/
│   │   ├── signer-service/        (Rust)
│   │   ├── identity-service/      (Rust)
│   │   └── ...
│   ├── roxy-gateway/
│   │   ├── gateway-service/       (Go)
│   │   └── ...
│   ├── roxy-processing/
│   │   ├── scheduler/             (Go)
│   │   └── ...
│   ├── roxy-interface/
│   │   └── webui/                 (Node.js)
│   └── roxy-system/
│       ├── system-services-1/     (Java - Maven)
│       ├── system-services-2/     (Java - Gradle)
│       └── system-services-3/     (Python)
├── tests/                         (Test suite)
├── README.md                      (Architecture guide)
└── setup.sh                       (Initialization)

Key architectural principle: Services are organized by functional domain (identity, gateway, processing, interface, system), not by language. This makes ownership clear and teams focused.

🔍Step 4: Map Services to Languages

ROXY-SYSTEMS is polyglot. Understanding which services use which languages helps you:

Know what validation tools to expect for each service
Choose which service to start with based on your comfort
Understand deployment complexity

🦀 Rust Services
signer-service
identity-service
gateway-auth-client
gateway-service
token-minter

🐹 Go Services
scheduler
boundary-adapter
veto-service
rdb-updater
sharding-router

🟢 Node.js Services
webui
(TypeScript)

☕ Java Services
system-services-1 (Maven)
system-services-2 (Gradle)
🐍 Python
system-services-3

Pro tip: Start with a service in a language you know. The workflow is identical regardless of language—only the validation changes.

✨Step 5: Manage Work with c-issue

Stop digging through browser tabs. COSMOS brings issue management to your terminal.

Find a task:

c-issue list good-first-issue

This fetches live data from the repo. You'll see tasks perfect for new engineers.

Or create a new task interactively:

c-issue interactive

The wizard will guide you through:

Repo Selection: Auto-detected from Membrane
Category: small-bug-fixes, feature, etc.
Priority: Critical/High/Medium/Low

💡 Insight: c-issue is adapter-aware. Whether we use GitHub Issues, Jira, or Linear, the CLI command remains the same.

🛠️Step 6: Make Your Change

Navigate to your service:

cd src/[domain]/[service-name]

Make your change:

Update code, fix a bug, or improve docs. Keep it focused.

Validate locally:

COSMOS standardizes validation commands:

Rust cargo check && cargo test

Go go test ./...

✅Step 7: Validate Your Changes

Before committing, ensure your code passes language-specific validation. COSMOS will do this automatically, but testing locally first saves time.

Rust services:

cargo check && cargo test

Go services:

go build ./... && go test ./...

Node.js services:

npm install && npm run lint && npm test

Java (Maven):

mvn clean compile -DskipTests

Java (Gradle):

gradle build -x test

Python:

python -m py_compile . && python -m pytest

Success looks like: No errors, maybe some warnings. If you see failures, fix them and try again.

💾Step 8: Commit with COSMOS

Navigate back to repo root:

cd ~/Code/roxy-systems

Check what changed:

git status

Run the commit tool:

c-commit

COSMOS will now:

Run language validation (cargo check, npm lint, etc.)
Ask for commit metadata:
- Type: 1 (feat), 2 (fix), 4 (docs), 5 (chore)
- Message: Your brief description
- Scope: Service name (auto-filled)
Format conventionally: type(scope): message
Save to git with full history

Example interaction:

:: INITIATING PRE-COMMIT SHIELDS ::
Checking Rust (cargo check)... PASSED
✓ All shields passed

:: STAGING CHANGES ::
✓ All changes staged

:: SELECT CHANGE TYPE ::
1) feat   2) fix   3) refactor   4) docs   5) chore   6) style   7) test   8) perf
Selection: 4
Message: improve signer-service documentation
Scope: signer-service
Finalize? (y/n): y

✓ Commit successful!

🌐Step 9: Share with the Team

Push your changes:

git push

What happens next:

Your commit appears on GitHub
GitHub Actions runs your service's tests
Team members can see your contribution in the activity feed
Your name is now in the codebase history

Create a pull request (optional for documentation):

If you changed code (not just docs), create a PR on GitHub for team review. Steps:

Go to the repository on GitHub
Click "Pull Requests" tab
Click "New Pull Request"
Select your branch (should show your commit)
Add a description: what changed and why
Click "Create Pull Request"

The team will review and either approve or ask for changes.

🔄Step 10: Watch the CI/CD Pipeline

ROXY-SYSTEMS has two connected CI/CD pipelines triggered by git tags created by COSMOS:

🏗️ Control Plane
build-base-images.yml
Builds language base images (Rust, Go, Node, Java, Python) weekly

🚀 Application Plane
build-and-push.yml
Triggered by service release tag, builds & signs Docker image

Watch your commit's validation:

Go to the GitHub repository
Click "Actions" tab
Find your service's workflow run
Watch it execute in real-time

Your workflow will:

✅ Check out code
✅ Run language-specific tests
✅ Build the service
✅ Run security scan (Trivy for CVEs)
✅ Sign the image (cosign)
✅ Push to Artifact Registry

🎉 If everything passes: Your code is validated, tested, and ready for production. The image is signed and scanned automatically.

📊Understanding the Pipelines

Control Plane (Weekly Base Images)

Runs on schedule or when Dockerfile.base-* files change:

Dockerfile.base-rust modified ↓ GitHub detects push to Dockerfile.base-* ↓ Triggers build-base-images.yml ↓ Builds multi-platform images (linux/amd64) ↓ Pushes to us-east1-docker.pkg.dev ↓ Language teams use these for building services

Application Plane (Service Releases)

Triggered when COSMOS creates a version tag:

Developer runs c-linker signer-service ↓ Creates git tag: signer-service-v1.0.1 ↓ Developer runs git push --follow-tags ↓ GitHub detects tag matching *-v*.*.* pattern ↓ Triggers build-and-push.yml automatically ↓ Authenticates to GCP (no keys stored!) ↓ Builds Docker image with base image ↓ Scans for CVEs (Trivy) ↓ Signs image (cosign) with provenance ↓ Pushes to Artifact Registry ↓ Updates Kubernetes manifests ↓ Rolls out to production

🔐 Security Note: GitHub Actions authenticates to GCP via Workload Identity Federation—no service account keys are stored or exposed. Tokens are temporary (~1 hour) and scoped to minimal permissions.

👥Your Team's Expectations

Now that you're part of ROXY-SYSTEMS, here's what the team expects:

✅ DO

Always use c-commit
Test locally before pushing
Write clear commit messages
Ask questions in chat
Review PRs from teammates

❌ DON'T

Use git commit directly
Push broken code
Edit infrastructure files
Force-push history
Release without approval

Why this matters:

c-commit ensures consistent formatting and validation
Testing prevents broken builds and cascading failures
Infrastructure is team-maintained; changes need coordination
Git history is the team's audit trail—never rewrite it
Releases are permanent; they need approval and review

🎯Common Scenarios

Scenario 1: Fix a Typo in Code

cd src/roxy-identity/signer-service # Fix the typo c-commit # Type: fix # Scope: signer-service # Message: correct parameter name in validation git push

Scenario 2: Add Documentation

cd src/roxy-processing/scheduler # Update README c-commit --no-verify # Type: docs # Scope: scheduler # Message: add job scheduling examples git push

Scenario 3: Add Tests for Existing Function

cd src/roxy-gateway/gateway-service # Add test file c-commit # Type: test # Scope: gateway-service # Message: add tests for rate limiter git push

Scenario 4: Complex Feature (Needs PR Review)

# Create feature branch git checkout -b feat/new-caching-layer # Make changes cd src/roxy-system/system-services-3 # ... edits ... # Commit (uses c-commit) c-commit git push origin feat/new-caching-layer # GitHub: Create PR for team review # Wait for approval # Merge when approved

⚠️Critical Rules

RULE 1: Only Edit src/ and tests/
Infrastructure (docker/, kubernetes/, deployment/) is managed centrally. Changes require team lead approval.

RULE 2: Always Use c-commit
Git hooks prevent direct git commit to enforce COSMOS workflow. If you get stuck, ask your team lead.

RULE 3: Test Locally First
Run language validation (cargo check, npm lint, etc.) before committing. Don't let broken code reach the team.

RULE 4: Never Force-Push History
Don't use git rebase, git reset --hard, or git push --force. History is immutable.

RULE 5: Ask Before Releasing
Only team leads run c-linker. Releases are permanent and affect production.

🚀Step 11: Release with c-linker

When your code is ready, don't just push. Link it.

c-linker is the smart orchestration tool that handles versioning, tagging, and cloud syncing.

Execute a Release:

c-linker src/roxy-identity/signer-service

The Linker Flow:

1. [CHECK] Cloud Registry (GCP/AWS) 2. [CHECK] Git Status & Branch 3. [BUMP] Semantic Version (v1.0.1 → v1.0.2) 4. [TAG] Git Tag (signer-service-v1.0.2) 5. [PUSH] Trigger Application Plane CI

🎉 Automation: Once c-linker pushes the tag, the CI pipeline takes over: building, signing, and deploying the artifact to the registry configured in .cosmos.cloud.env.

⚠️Critical Rules

RULE 1: Use the Tools
`c-issue` for tasks, `c-commit` for code, `c-linker` for releases. They keep the ecosystem strictly typed and synchronized.

RULE 2: Respect the Pulse
Run `c-pulse` before starting work. Ensure you aren't building on top of broken dependencies.

RULE 3: Infrastructure is Guarded
Changes to `docker/` or `deployment/` affect the entire fleet. These require specific approval.

🆘Troubleshooting

Q: "command not found: c-commit"
A: COSMOS isn't properly installed. Re-run ./install.sh in the cosmos-repo directory, then verify with c-pulse.

Q: "cargo check failed" or other validation error
A: This is intentional! COSMOS is preventing broken code from reaching the team. Fix the error and try c-commit again.

Q: I need to skip validation (docs-only change)
A: Use c-commit --no-verify or c-commit -n. But use sparingly—validation exists for good reason.

Q: Someone else pushed and I'm behind
A: Run git pull, resolve any conflicts (merge or discuss with teammate), then git push again.

Q: I committed something by mistake and want to undo
A: Ask your team lead. Undoing depends on whether it's been pushed. Never force-push; let the team help.

Q: The CI/CD pipeline is failing
A: Check the workflow logs on GitHub (Actions tab). Most failures are validation errors that need fixing. Ask your team if stuck.

Q: I accidentally edited a docker/ or kubernetes/ file
A: Don't commit it! Run git checkout -- docker/ or git checkout -- kubernetes/ to revert. Then ask your team lead if the change was necessary.

📚Learning Resources

Documentation in the repository:

README.md – Full architecture explanation
SETUP.md – Environment setup details
src/[service]/README.md – Service-specific guides
.github/workflows/ – Actual CI/CD pipelines

Online resources:

COSMOS Welcome – Quick start guide (you've done this!)
GitHub Actions Docs – docs.github.com/actions
Kubernetes Docs – kubernetes.io/docs
Language-specific docs (Rust, Go, Node, Java, Python)

Team chat & meetings:

Ask questions in #dev-help or your team channel
Attend architecture reviews (usually weekly)
Shadow more experienced developers during releases

🎓Next Steps (After Your First Commit)

Make 5-10 more commits to build confidence with the workflow
Read the full README.md to understand system architecture
Review another service's code to see different languages in action
Attend a team meeting to understand decision-making
Observe a release with your team lead to see the full pipeline
Review the CI/CD workflows (.github/workflows/) to understand automation
Help review PRs from teammates—code review is how we learn together

🎉You're Ready!

You now possess the full toolchain:

install.sh for environment sync
c-pulse for real-time situational awareness
c-issue for workflow management
c-linker for production releases

Welcome to ROXY-SYSTEMS. Go check the pulse and make your mark. 🚀

🚀ROXY-SYSTEMS

✅Prerequisites Check

🏗️Step 1: Clone & Initialize ROXY-SYSTEMS

Clone the repository:

Run the installer:

Verify setup worked:

📋Step 2: Understand cosmos.json

📋Step 2.5: Cloud & Issue Configuration

1. Configure Issue Tracking:

2. Configure Cloud Registry (First Time Only):

🗂️Step 3: Explore the Directory Structure

See the full layout:

What you'll see:

🔍Step 4: Map Services to Languages

✨Step 5: Manage Work with c-issue

Find a task:

Or create a new task interactively:

🛠️Step 6: Make Your Change

Navigate to your service:

Make your change:

Validate locally:

✅Step 7: Validate Your Changes

Rust services:

Go services:

Node.js services:

Java (Maven):

Java (Gradle):

Python:

💾Step 8: Commit with COSMOS

Navigate back to repo root:

Check what changed:

Run the commit tool:

🌐Step 9: Share with the Team

Push your changes:

Create a pull request (optional for documentation):

🔄Step 10: Watch the CI/CD Pipeline

Watch your commit's validation:

📊Understanding the Pipelines

Control Plane (Weekly Base Images)

Application Plane (Service Releases)

👥Your Team's Expectations

🎯Common Scenarios

Scenario 1: Fix a Typo in Code

Scenario 2: Add Documentation

Scenario 3: Add Tests for Existing Function

Scenario 4: Complex Feature (Needs PR Review)

⚠️Critical Rules

🚀Step 11: Release with c-linker

Execute a Release:

⚠️Critical Rules

🆘Troubleshooting

📚Learning Resources

🎓Next Steps (After Your First Commit)

🎉You're Ready!