takaro-engineer
Takaro repository knowledge - monorepo structure, tests, Docker setup, debugging, database migrations, brittle test investigation. Use when working on this codebase, running tests, debugging issues, investigating flaky tests, or understanding the project structure. (project)
When & Why to Use This Skill
This Claude skill acts as a specialized engineering assistant for the Takaro repository, a web-based multi-gameserver manager. It provides comprehensive technical guidance on monorepo architecture, Docker-based development workflows, database migrations, and advanced testing strategies, enabling developers to navigate and maintain the codebase with high efficiency.
Use Cases
- Streamlining Development Workflows: Quickly execute Docker-based commands for running unit and integration tests, viewing logs, or accessing the database CLI.
- Monorepo Navigation: Understanding the relationships between packages like app-api, web-main, and lib-components to ensure proper architectural patterns.
- Debugging and QA: Investigating brittle or flaky tests using specialized scripts and analyzing domain-specific logs to resolve CI failures.
- Database Management: Handling PostgreSQL migrations, creating development data, and managing multi-tenancy configurations within the Takaro ecosystem.
- Environment Setup: Configuring the local stack including Node.js, Redis, and Ory Kratos authentication for a consistent development experience.
| name | takaro-engineer |
|---|---|
| description | Takaro repository knowledge - monorepo structure, tests, Docker setup, debugging, database migrations, brittle test investigation. Use when working on this codebase, running tests, debugging issues, investigating flaky tests, or understanding the project structure. (project) |
Takaro Engineer
Essential knowledge for the Takaro repository - a web-based multi-gameserver manager.
Quick Reference
| Task | Command |
|---|---|
| Run specific test | docker compose exec takaro npm run test:file <path> |
| Run unit tests | docker compose exec takaro npm run test:unit |
| Run integration tests | docker compose exec takaro npm run test:integration |
| Shell into container | docker compose exec takaro bash |
| View logs | docker compose logs --tail=50 takaro |
| Database CLI | docker compose exec postgresql psql -U takaro -d takaro |
| Run migrations | docker compose exec takaro npm -w packages/app-api run db:migrate |
| Create dev data | docker compose exec takaro node scripts/dev-data.mjs |
| Reset dev data | docker compose exec takaro node scripts/dev-remove-domains.mjs |
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
| Port | Service |
|---|---|
| 13000 | API |
| 13001 | web-main (frontend) |
| 13002 | Storybook |
| 13005 | Documentation |
| 13100 | PostgreSQL |
| 6379 | Redis |
| 4433 | Kratos (auth) |
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
- Internal packages as peerDependencies: Add
@takaro/*packages topeerDependencieswith*version - Tests log domain ID: Failed tests print domain ID - grep logs with it
- TypeScript check before tests: Every test run validates types first (~2s overhead)
- Dangling domains cleanup: Test framework auto-removes
integration-*prefixed domains - Frontend components: Always use lib-components, never inline components