ROXY-SYSTEMS: Your Development Journey Continues

✅ Prerequisites

You should already know how to:

Open a terminal and navigate directories
Run git clone to download code
Use c-commit to save changes
Use git push to share code
Understand what a monorepo is

If any of that is fuzzy, review the COSMOS guide first.

🔥 Step 1: Clone ROXY-SYSTEMS

Navigate and clone:

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

Move into the directory:

cd roxy-systems

Verify the structure:

ls -la

You should see docker/, kubernetes/, deployment/, src/, tests/ directories and setup files.

⚙️ Step 2: Initialize Git Hooks

ROXY-SYSTEMS enforces COSMOS usage. Set it up:

./setup.sh

This checks COSMOS, detects your languages, and installs git hooks that prevent bypassing COSMOS.

Verify everything works:

c-pulse

You should see a formatted table of all services with their versions and status.

🔍 Step 3: Explore the Codebase

See the entire ecosystem:

c-audit

Check the actual directory structure:

tree -L 2

You'll see:

docker/ - Containerization configs
kubernetes/ - Orchestration (base, overlays for dev/staging/prod, monitoring)
deployment/ - Scripts for deploying and rolling back
src/ - Where the actual application code lives
tests/ - Test suite

Look at src/ to find your service:

ls -la src/

This shows you the application code you can edit.

✏️ Step 4: Make Your First Real Change

Where you can safely edit:

src/ - Application source code (SAFE TO EDIT)
tests/ - Test files (SAFE TO EDIT)
docker/ - Container configs (ASK BEFORE EDITING)
kubernetes/ - K8s configs (ASK BEFORE EDITING)
deployment/ - Deploy scripts (ASK BEFORE EDITING)

For your first change, edit something in src/:

cd src

Look at what's there:

ls -la

Open your editor:

code .

Make a small, safe change: Update a comment, add documentation, or modify a string. Keep it simple—you're learning the workflow.

⚠️ DO NOT EDIT DOCKER OR KUBERNETES FILES YET. Ask your team lead before touching those.

Return to terminal when done.

🧪 Step 5: Validate Your Change

Before committing, ensure your code compiles:

Synapse Core (Rust):

cargo check

WebUI (Node.js):

npm run lint

Scheduler (Go):

go build ./...

System Services (Java/Python):

mvn clean compile -DskipTests

Success looks like: "Finished successfully" or no errors. If you see errors, fix them and try again.

💾 Step 6: Commit Your Change

Navigate back to repo root:

cd ~/Code/roxy-systems

Run the commit tool:

c-commit

Answer the prompts:

Selection: Pick 1 (feat), 2 (fix), 4 (docs), etc.
Message: Brief description of your change
Scope: Service name (auto-filled)
Finalize: Type y to confirm

✅ Your commit is saved!

🌐 Step 7: Share With the Team

Push your code to GitHub:

git push

Visit GitHub to see your commit in the activity feed. Your name is now in the team's code history!

📊 Step 8: Understanding the Monorepo Structure

ROXY-SYSTEMS is an enterprise monorepo containing microservices, containerization, orchestration, and deployment infrastructure:

roxy-systems/
├── docker/                          (Container images)
│   ├── Dockerfile.synapse
│   ├── Dockerfile.webui
│   ├── Dockerfile.scheduler
│   └── Dockerfile.system1-3
├── kubernetes/                      (Orchestration)
│   ├── base/                        (Core configs)
│   │   ├── synapse-core.yaml
│   │   ├── webui.yaml
│   │   ├── scheduler.yaml
│   │   └── systems.yaml
│   ├── overlays/                    (Env-specific)
│   │   ├── dev/
│   │   ├── staging/
│   │   └── production/
│   └── monitoring/                  (Observability)
├── deployment/                      (Release tools)
│   ├── deploy.sh
│   ├── validate.sh
│   ├── rollback.sh
│   └── config/
├── src/                             (Application code)
├── tests/                           (Test suite)
└── README.md

Key directories:

docker/ - Container definitions for all services
kubernetes/ - Orchestration configs for dev, staging, production
deployment/ - Scripts and configs for deploying and rolling back changes
src/ - Application source code (your main working directory)
tests/ - Automated test suite

Key architectural points:

COSMOS manages versioning across all services in the monorepo
Docker/Kubernetes files are infrastructure-level—don't edit without team lead approval
Deployment scripts use COSMOS tags to release code to different environments
Never manually edit kubernetes configs in production environments
Always test changes locally before committing to the shared repository

🎯 Step 9: Releases (Team Leads Only)

⚠️ RELEASES ARE PERMANENT. Only team leads should execute releases. Ask for approval and assistance before attempting this.

Preview a release (non-destructive):

c-test src/your-service-name

Example:

c-test src/synapse-core

Execute a release (team lead only, with approval):

c-linker src/your-service-name

Then push the release tags:

git push --follow-tags

How releases work:

c-test creates a release candidate and validates it across all environments
c-linker finalizes the release and creates immutable git tags
git push --follow-tags shares the release with the entire team
The deployment/ scripts then use these tags to deploy to kubernetes

📋 Daily Workflow

MORNING: CHECK STATUS c-pulse THROUGHOUT DAY: MAKE CHANGES Edit files in src/ → Test locally WHEN DONE: COMMIT c-commit BEFORE LEAVING: SHARE git push RELEASE DAY: (TEAM LEADS ONLY) c-test src/service-name c-linker src/service-name git push --follow-tags

⚠️ Important Rules

RULE 1: Always use c-commit, never git commit. The repo blocks direct commits.

RULE 2: Test locally before committing. Don't let broken code reach the team.

RULE 3: Never modify git history. Don't use git rebase, git reset --hard, or git push --force.

RULE 4: Ask before releasing. Only team leads should run c-linker.

RULE 5 - CRITICAL: Only edit src/ and tests/ directories. Never edit docker/, kubernetes/, or deployment/ without explicit team lead approval.

🛠️ Troubleshooting

Q: "command not found: c-commit"
A: COSMOS isn't installed. Go to https://cosmos-welcome.roxy.systems to install or reinstall COSMOS.

Q: My validation failed and I can't commit
A: Fix the errors (run cargo check, npm run lint, etc.) then try c-commit again.

Q: I need to skip validation (docs update)
A: Use c-commit --no-verify or c-commit -n

Q: "This commit would override history"
A: Someone pushed before you. Run git pull, merge, then git push again.

Q: How do I undo my last commit?
A: Ask your team lead. It depends on whether it's been pushed.

Q: I edited docker/ or kubernetes/ by mistake
A: Don't commit it! Use git checkout -- docker/ or git checkout -- kubernetes/ to revert, then ask your team lead if the change was necessary.

Q: Things are broken and I don't know what to do
A: Visit https://cosmos-welcome.roxy.systems for help—it has detailed troubleshooting guides and reinstall instructions.

📚 Next Steps

Make 5-10 commits to get comfortable with the workflow
Read SETUP.md for project-specific details
Ask questions in team chat—everyone started here
Review recent commits: git log --oneline -20
Observe a release with a team lead to see how the full pipeline works
Read the main README.md for detailed architecture documentation

🎉 You've Got This!

You now understand:

How to navigate a multi-language monorepo safely
How to make changes to src/ with proper validation
How to commit consistently using COSMOS
How to share code and collaborate with your team
How releases work and why they require approval
Why infrastructure files are off-limits without permission

Welcome to the ROXY-SYSTEMS team! You're ready to contribute real code. Start small, ask questions, and grow from there. 🚀

🚀 ROXY-SYSTEMS: Your Development Journey Continues