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

Both binaries share the same PostgreSQL database. The management-plane binary reads merchant counts directly from the shared DB rather than receiving them via HTTP 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.0: Database Layer Architecture​

Before touching API code, it helps to understand how persistence is structured.

The Store trait in rust/api/src/db/mod.rs is the abstract database interface, but its body is empty — it is purely a supertrait that combines nine aggregate-specific stores:

pub trait Store:
    AuthStore
    + LocationStore
    + TransactionStore
    + WebhookStore
    + RetryStore
    + BillingStore
    + LroeStore
    + AuditStore
    + TelemetryStore
    + Send + Sync {}

Each sub-trait lives in its own file (auth_store.rs, location_store.rs, etc.) and owns a cohesive slice of persistence. There is exactly one implementation (PgStore) against PostgreSQL — the former SQLite backend has been removed, so handlers depend on Arc<dyn Store> without a backend-selection branch.

When adding a new database method:

  1. Find the sub-trait that owns that aggregate (or create a new one if the method defines a new aggregate).
  2. Add the method signature to the trait file.
  3. Implement it on PgStore in rust/api/src/db/postgres.rs, inside the impl <SubTrait> for PgStore block (impls are split per trait).
  4. Handlers continue to take Arc<dyn Store> — the method resolves through the supertrait bound.

Do not add methods back to the Store trait body itself. Keeping the aggregates separate is what makes it tractable to stub Store in tests and review a single domain in isolation.

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)