takaro-engineer

Takaro Engineer

Essential knowledge for the Takaro repository - a web-based multi-gameserver manager.

Quick Reference

Stack

• Runtime: Node.js 24.11.0, TypeScript 5.5.4
• Backend: Express, routing-controllers, Objection.js/Knex
• Frontend: React 18, TanStack Router, styled-components
• Database: PostgreSQL 15, Redis 7.2
• Auth: Ory Kratos
• Testing: Node.js test runner (backend), Vitest (frontend)

Ports

Monorepo Structure

packages/
├── app-api          # Main API server
├── app-connector    # Game server connector
├── app-mock-gameserver  # Mock gameserver for testing
├── lib-*            # Shared libraries
├── web-main         # Frontend (React)
├── web-docs         # Documentation (Docusaurus)
└── lib-components   # UI component library

Detailed Guides

• DEV-ENVIRONMENT.md - Dev data setup, credentials, Playwright testing
• TESTING.md - Test framework, commands, debugging failures
• DEBUGGING.md - CI failures, log analysis, domain ID tracing
• BRITTLE-TESTS.md - Investigating and fixing flaky tests
• DATABASE.md - Multi-tenancy, migrations, useful queries
• DOCKER.md - Services, exec commands, compose files
• API.md - Controller patterns, adding endpoints, permissions
• FRONTEND.md - lib-components, web-main, storybook
• MODULES.md - Module system, commands, hooks, testing

Helper Scripts

# Find test files
./scripts/find-test.sh <pattern>

# Database debugging queries
./scripts/psql-debug.sh <query-name>

# CI failure logs
./scripts/ci-logs.sh <PR_NUMBER> [search_pattern]

Key Gotchas

1. Internal packages as peerDependencies: Add @takaro/* packages to peerDependencies with * version
2. Tests log domain ID: Failed tests print domain ID - grep logs with it
3. TypeScript check before tests: Every test run validates types first (~2s overhead)
4. Dangling domains cleanup: Test framework auto-removes integration-* prefixed domains
5. Frontend components: Always use lib-components, never inline components