Skip to main content

Zyntem Fiscalization - Developer Onboarding Guide

Version: 1.1 Last Updated: 2026-03-15 Estimated Completion Time: 2-3 hours

Welcome to Fiscalization by Zyntem! 🎉​

This guide will walk you through everything you need to become a productive member of the Fiscalization by Zyntem development team. By the end of this onboarding, you'll have:

✅ Development environment fully configured ✅ Understanding of testing practices ✅ Knowledge of deployment procedures ✅ Access to all necessary tools and documentation

Before You Start:

  • Ensure you have admin access to your machine (required for tool installation)
  • Have your GCP account credentials ready (or coordinate with team lead)
  • Set aside 2-3 hours for uninterrupted setup

Onboarding Roadmap​

graph TD
    A[Start: Read This Guide] --> B[Phase 1: Environment Setup - 1h]
    B --> C[Phase 2: Understand Testing - 30min]
    C --> D[Phase 3: Learn CI/CD - 20min]
    D --> E[Phase 4: Deployment Knowledge - 30min]
    E --> F[Phase 5: First Contribution - Variable]
    F --> G[Complete: You're Ready! 🚀]

Phase 1: Environment Setup (1 hour)​

Step 1.1: Read Prerequisites​

Action: Read SETUP.md

Focus On:

  • Required tools and versions
  • OS-specific installation instructions
  • GCP prerequisites

Time: 10 minutes

Step 1.2: Install Development Tools​

Follow: SETUP.md - Installation Instructions

Your Operating System:

  • macOS (recommended: use Homebrew)
  • Linux (Ubuntu/Debian)
  • Windows (use WSL2)

Tools to Install:

# Checklist (verify each):
[ ] Go 1.24+
[ ] Node.js 20+
[ ] Docker and Docker Compose v2+
[ ] golang-migrate CLI
[ ] Git 2.30+
[ ] make
[ ] jq
[ ] curl

Commands for macOS (Quick Reference):

# Install core tools
brew install go node git jq
brew install golang-migrate

# Install Docker Desktop
open -a Docker

# Verify
go version          # Should be 1.24+
node --version      # Should be 20+
migrate -version    # golang-migrate CLI
docker --version    # Docker with Compose v2

Time: 20-30 minutes (depending on download speeds)

Checkpoint: ✅ All tools installed? If not, see SETUP.md - Troubleshooting

Step 1.3: Setup GCP Access​

Follow: SETUP.md - GCP Prerequisites

Steps:

  1. Create GCP Account (if you don't have one)

  2. Create Development Project

    gcloud auth login
    gcloud projects create zyntem-dev-YOUR_NAME --name="Fiscalization Dev - Your Name"
    gcloud config set project zyntem-dev-YOUR_NAME

  3. Enable Required APIs

    gcloud services enable \
      run.googleapis.com \
      sqladmin.googleapis.com \
      secretmanager.googleapis.com \
      storage.googleapis.com

  4. Create Service Account

    gcloud iam service-accounts create zyntem-dev \
      --display-name="Fiscalization Development"

    # Grant roles (see SETUP.md for full commands)

  5. Download Credentials

    mkdir -p ~/.gcp
    gcloud iam service-accounts keys create ~/.gcp/zyntem-dev-key.json \
      --iam-account=zyntem-dev@zyntem-dev-YOUR_NAME.iam.gserviceaccount.com

    echo 'export GOOGLE_APPLICATION_CREDENTIALS=~/.gcp/zyntem-dev-key.json' >> ~/.bashrc
    source ~/.bashrc

Time: 15-20 minutes

Checkpoint: ✅ Can you run gcloud projects list and see your project?

Step 1.4: Validate Environment​

Action: Run environment validation

# Clone repository (if not already done)
git clone https://github.com/zyntem/fiscalization.git
cd fiscalization

# Run validation script
./scripts/validate-environment.sh

Expected Output:

✓ Go detected (1.24+)
✓ Node.js detected (20+)
✓ Docker detected
✓ Git detected
✓ make detected
✓ jq detected
✓ curl detected

All prerequisites met! ✓
You are ready to start development.

If Validation Fails:

Time: 5 minutes

Checkpoint: ✅ Validation script passes?

Step 1.5: Start Local Services​

Action: Start Docker Compose stack

# Start all services (PostgreSQL, Redis)
docker-compose up -d

# Verify services are running
docker-compose ps

# Check PostgreSQL is accessible
psql -h localhost -p 5432 -U fiscalization -d fiscalization_dev
# Password: dev_password (see docker-compose.yml)

# Check Redis is accessible
redis-cli -h localhost -p 6379 ping
# Expected: PONG

Time: 5 minutes

Checkpoint: ✅ PostgreSQL and Redis running?

Phase 2: Understand Testing (30 minutes)​

Step 2.1: Read Testing Guide​

Action: Read TESTING.md

Focus On:

  • Test categories (unit, integration, E2E)
  • Go testing with testify
  • TypeScript testing with Vitest
  • Code coverage requirements (80% Go, 75% TypeScript)

Time: 15 minutes

Key Takeaways:

  • ✅ Epic 1 stories focus on unit tests only
  • ✅ Integration tests begin in Epic 2
  • ✅ Use Arrange-Act-Assert pattern
  • ✅ Test behavior, not implementation
  • ✅ Table-driven tests for multiple scenarios

Step 2.2: Explore Test Examples​

Action: Review example tests

# Go test examples (once Story 1.0b is complete)
cat internal/testutil/example_test.go

# TypeScript test examples
cat tests/example.test.ts

# Run tests (after Story 1.0b)
make test

# Generate coverage report
make test-coverage
open coverage.html

Time: 10 minutes

Checkpoint: ✅ Understand how to write and run tests?

Step 2.3: Testing Quick Reference​

Commands to Bookmark:

# Run all tests
make test

# Run Go tests only
go test ./...

# Run TypeScript tests only
npm test

# Watch mode (re-run on changes)
make test-watch

# Generate coverage
make test-coverage

# Run specific test
go test -run TestTransactionService_Create ./internal/service

Time: 5 minutes

Phase 3: Learn CI/CD (20 minutes)​

Step 3.1: Understand Pipeline​

Action: Read CI-CD.md

Focus On:

  • Pipeline architecture (Lint → Test → Build → Deploy)
  • Workload Identity Federation (keyless GCP auth)
  • How deployments trigger automatically
  • Local testing before push

Time: 10 minutes

Key Takeaways:

  • ✅ Every push to main triggers deployment to dev
  • ✅ Pull requests run tests but don't deploy
  • ✅ Pipeline takes ~20 minutes (main) or ~15 minutes (PRs)
  • ✅ Can run same checks locally: make test && make lint

Step 3.2: Test Local CI Checks​

Action: Run CI checks locally

# Lint (Go — same as CI gate)
cd apps/core-api && gofmt -l . | (! grep .)

# Build
cd apps/core-api && go build ./...

# Test (requires test DB)
cd apps/core-api && go test ./... -count=1

# Conformance
make conformance-check

Time: 5 minutes

Checkpoint: ✅ Can you run CI checks locally without errors?

Step 3.3: Review Pipeline Status​

Action: Check GitHub Actions

  1. Visit: https://github.com/zyntem/fiscalization/actions
  2. Review recent workflow runs
  3. Click on a failed run (if any) to see logs
  4. Understand how to debug CI failures

Time: 5 minutes

Phase 4: Deployment Knowledge (30 minutes)​

Step 4.1: Understand Deployment Strategy​

Action: Read DEPLOYMENT.md

Focus On:

  • Blue-green deployment with gradual traffic shifting
  • Health check requirements
  • Rollback procedures (automatic and manual)
  • Database migration best practices

Time: 15 minutes

Key Takeaways:

  • ✅ Deployments use blue-green strategy (zero downtime)
  • ✅ Traffic shifts gradually: 10% → 50% → 100%
  • ✅ Automatic rollback if error rate > 5% or P99 latency > 2s
  • ✅ Manual rollback takes < 30 seconds

Step 4.2: Review Deployment Checklist​

Action: Skim DEPLOYMENT-CHECKLIST.md

Note: You won't deploy on Day 1, but familiarize yourself with:

  • Pre-deployment checks
  • Monitoring during deployment
  • Post-deployment verification

Time: 5 minutes

Step 4.3: Explore Operational Runbook​

Action: Skim RUNBOOK.md

Bookmark Sections:

  • System Architecture (overview of all services)
  • Common Issues (troubleshooting guide)
  • Emergency Procedures (rollback, database restore)

Time: 10 minutes

Checkpoint: ✅ Know where to look when issues arise?

Phase 4b: Billing & Licensing (10 minutes)​

Billing (Stripe)​

The platform uses Stripe for subscription management. Relevant env vars:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...
STRIPE_PRICE_ID_MONTHLY=price_...
STRIPE_PRICE_ID_ANNUAL=price_...

Webhooks are handled in apps/core-api/internal/stripe/. See .env.example for all Stripe variables.

License Enforcement​

The management plane enforces per-tier limits on agents and merchants:

TierAgentsMerchantsGrace Period
Trial157 days
Starter55030 days
Professional2550030 days
EnterpriseUnlimitedUnlimited90 days

Core-API reports merchant counts to the management plane via heartbeat.

Rate Limiting​

All API endpoints are rate-limited by tier:

TierRequests/minBurst
Sandbox100200
Starter1,0002,000
Growth5,00010,000
Enterprise20,00040,000

Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included on all responses.

Phase 5: First Contribution (Variable Time)​

Step 5.1: Find a Good First Issue​

Action: Pick a starter task

Options:

  1. Documentation Improvement (Low risk, great for learning)

    • Fix typos in docs
    • Add examples to TESTING.md
    • Improve troubleshooting sections

  2. Test Writing (After Story 1.0b)

    • Add test cases to existing functions
    • Improve test coverage in specific package
    • Write table-driven tests for validation functions

  3. Small Feature (After Epic 1 completion)

    • Add validation rule for new country
    • Implement helper function
    • Add new API endpoint (with tests)

Find Issues:

  • GitHub Issues tagged good-first-issue
  • Ask team lead for recommendations
  • Review current sprint backlog

Time: Variable

Step 5.2: Development Workflow​

Typical Workflow:

  1. Create Branch

    git checkout -b feature/your-feature-name

  2. Make Changes

    # Edit code
    # Write tests (TDD: test first!)

  3. Run Tests Locally

    make test
    make lint

  4. Commit & Push

    git add .
    git commit -m "feat: add feature X

    - Implemented feature X
    - Added unit tests with 85% coverage
    - Updated documentation"

    git push origin feature/your-feature-name

  5. Create Pull Request

    • Visit GitHub
    • Create PR from your branch to main
    • Fill out PR template
    • Request review from team lead

  6. Address Review Comments

    • Make requested changes
    • Push updates to same branch
    • PR updates automatically

  7. Merge

    • Once approved, merge PR
    • Delete branch
    • CI/CD deploys to dev automatically

Step 5.3: Code Review Checklist​

Before Requesting Review:

  • All tests pass locally: make test
  • Linting passes: make lint
  • Code coverage ≥ 80%: make test-coverage
  • Documentation updated (if needed)
  • Commit messages follow convention
  • PR description explains what/why/how

Onboarding Checklist​

Track your progress through onboarding:

Phase 1: Environment Setup ✅​

  • Read SETUP.md
  • Installed all development tools
  • Setup GCP account and project
  • Created service account and downloaded credentials
  • Validation script passes
  • Local services (PostgreSQL, Redis) running

Phase 2: Testing ✅​

  • Read TESTING.md
  • Reviewed test examples
  • Ran tests locally
  • Understand coverage requirements

Phase 3: CI/CD ✅​

  • Read CI-CD.md
  • Understand pipeline flow
  • Ran CI checks locally
  • Reviewed GitHub Actions

Phase 4: Deployment ✅​

  • Read DEPLOYMENT.md
  • Reviewed DEPLOYMENT-CHECKLIST.md
  • Skimmed RUNBOOK.md
  • Bookmarked operational docs

Phase 5: First Contribution ✅​

  • Found a good first issue
  • Created feature branch
  • Made changes with tests
  • Created pull request
  • Merged to main

Quick Reference Card​

Essential Commands:

# Start services
docker-compose up -d

# Run tests
make test

# Run specific test
go test -run TestName ./path/to/package

# Lint code
make lint

# Generate coverage
make test-coverage

# Build services
make build

# Deploy (via CI/CD)
git push origin main

Essential URLs:

Documentation Index:

Common Onboarding Questions​

Q: How long until I can contribute code?​

A: You can start contributing after Phase 2 (testing knowledge). Most developers make their first PR within 3-4 hours of starting onboarding.

Timeline:

  • Day 1: Environment setup, read docs, small documentation fixes
  • Day 2-3: Write tests, fix bugs, small features
  • Week 2: Comfortable with full development workflow
  • Week 4: Autonomous contributor

Q: Who do I ask for help?​

A:

  1. First: Check documentation (SETUP.md, TESTING.md, etc.)
  2. Second: Search GitHub Issues for similar problems
  3. Third: Ask in Slack #zyntem-dev
  4. Fourth: DM team lead directly

Don't hesitate to ask! Everyone was new once.

Q: What if I break something?​

A:

  • Dev environment: Can't break anything permanent. Rollback is instant.
  • Tests: CI/CD blocks bad code from merging
  • Database: Migrations are backward-compatible and reversible

Remember: We have safeguards. It's hard to break things permanently.

Q: How do I stay updated on project changes?​

A:

  1. Watch repository: GitHub → Watch → Custom → Select notifications
  2. Read PRs: Review recent merged PRs weekly
  3. Attend standups: Daily team sync (if applicable)
  4. Check Slack: #fiscalization-announcements channel

Q: What's the coding style?​

A:

  • Go: Follow Effective Go + gofmt formatting (CI blocks unformatted code)
  • TypeScript: ESLint + Prettier (enforced in CI)
  • Commit messages: Conventional Commits (feat:, fix:, docs:, etc.)
  • Tests required: 50% coverage minimum per module

Key principles:

  • Write tests first (TDD)
  • Keep functions small (<50 lines)
  • Comment complex logic
  • Update docs with code changes

Troubleshooting Onboarding Issues​

Issue: Validation Script Fails​

Symptom: ./scripts/validate-environment.sh reports missing tools

Solution:

  1. Check which tool is missing
  2. Re-run installation commands for that tool
  3. Verify PATH is set correctly: echo $PATH
  4. Restart terminal and try again

Issue: Docker Services Won't Start​

Symptom: docker-compose up fails or services crash

Solution:

# Check Docker Desktop is running
open -a Docker

# Check ports aren't in use
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis

# Reset Docker Compose
docker-compose down -v
docker-compose up -d

Issue: GCP Authentication Errors​

Symptom: ERROR: (gcloud.auth.login) ...

Solution:

# Re-authenticate
gcloud auth login
gcloud auth application-default login

# Verify credentials
gcloud auth list
echo $GOOGLE_APPLICATION_CREDENTIALS

# Check service account key exists
ls -la ~/.gcp/zyntem-dev-key.json

Issue: Tests Fail Locally​

Symptom: make test fails but unclear why

Solution:

# Run tests with verbose output
go test -v ./...

# Run specific failing test
go test -run TestName -v ./path/to/package

# Check test database is running
docker-compose ps postgres

# Check environment variables
env | grep DATABASE_URL

Next Steps After Onboarding​

Once you've completed all phases:

Week 1 Goals​

  • Make first documentation PR
  • Write tests for existing code
  • Fix a small bug
  • Review teammate's PR

Week 2 Goals​

  • Implement small feature (with tests)
  • Participate in code review
  • Deploy to dev environment
  • Contribute to planning discussion

Month 1 Goals​

  • Complete Epic 1 story (or equivalent)
  • Mentor new developer through onboarding
  • Propose improvement to codebase
  • Present work in team demo

Feedback & Improvements​

This onboarding guide is a living document. Help us improve it!

Found an issue?

  • Create GitHub Issue with label onboarding
  • Or directly propose PR to improve this doc

Suggestions for improvement?

  • What was confusing?
  • What took longer than expected?
  • What would have helped you?

Contact:

Welcome to the Team! 🚀​

You've completed onboarding! Here's what you've accomplished:

✅ Development environment fully configured ✅ Understand testing practices and requirements ✅ Know how CI/CD pipeline works ✅ Familiar with deployment procedures ✅ Know where to find help and documentation

You're ready to contribute!

Remember:

  • Ask questions early and often
  • Tests are not optional
  • Documentation matters
  • Code review is for learning
  • Have fun building! 🎉

Onboarding Completed By: ___________________

Date: ___________

Time Taken: _______ hours

Notes:

(Any feedback or observations from your onboarding experience)

__________________________________________________
__________________________________________________
__________________________________________________

Additional Resources​

Learning Resources:

Fiscalization-Specific:

External Services:

Version History:

  • 2026-03-15: Added billing/licensing/rate limiting section, updated country support (v1.1)
  • 2025-10-29: Initial version (v1.0)