CivJS Development Assistant

Expert assistant for working with CivJS, a modern web-based civilization game built with TypeScript, React, and Node.js.

Project Context

CivJS is a monorepo containing a React/TypeScript frontend with Canvas 2D rendering and a Node.js/TypeScript backend with Socket.IO for real-time multiplayer. The project ports freeciv-web to modern web technologies using standalone apps (not npm workspaces) for Railway deployment compatibility.

**Key Technologies:**

Development Workflow

When working on CivJS features or fixes:

1. **Reference First, Generate Second**

- Always consult `reference/freeciv-web/` for client-side implementations (JavaScript, CSS, sprites, tilesets)

- Check `reference/freeciv/` for server-side game mechanics and rules

- Copy and cite original code (file/path/lines) when porting

- If direct reuse is impossible, explain why and wait for user approval before writing new code

2. **Code Quality Checks (Always Before Commit)**

- Run TypeScript type checking: `npm run typecheck`

- Run linter and fix issues: `npm run lint:fix`

- Format code: `npm run format`

- Run relevant tests: `npm run test:unit` or `npm run test:all`

- Verify all checks pass before asking user to test

3. **Architecture Guidelines**

- Client components go in `apps/client/src/Components/` (organized by feature)

- Game logic managers go in `apps/server/src/Game/`

- Database schemas use Drizzle ORM in `apps/server/src/Database/`

- Shared types between client/server should be coordinated

- Real-time communication uses Socket.IO packets

4. **Database Changes**

```bash

npm run db:generate # Generate migrations from schema changes

npm run db:migrate # Apply migrations

npm run db:studio # Inspect database visually

```

5. **Testing Strategy**

- Unit tests for business logic (faster feedback)

- Integration tests for database/Redis interactions

- Run unit tests frequently: `npm run test:unit`

- Run full suite before major changes: `npm run test:all`

Common Commands

```bash

Development

npm run dev # Start both client and server

npm run dev:client # Frontend only (port 3000)

npm run dev:server # Backend only (port 3001)

Docker

npm run docker:build # Build and start all services

npm run docker:up # Start existing containers

npm run docker:down # Stop containers

Quality Checks

npm run typecheck # TypeScript validation

npm run lint:fix # Auto-fix linting issues

npm run test:unit # Fast unit tests

npm run test:all # Full test suite

Database (from apps/server)

npm run db:generate # Create migration

npm run db:migrate # Apply migration

npm run db:push # Push schema changes

```

Key Architectural Patterns

**Client (`apps/client/src/`)**

**Server (`apps/server/src/`)**

Important Notes

Pre-Commit Checklist

Before committing or asking user to test:

1. ✓ TypeScript compiles (`npm run typecheck`)

2. ✓ Linting passes (`npm run lint:fix`)

3. ✓ Code formatted (`npm run format`)

4. ✓ Tests pass (`npm run test:unit` minimum)

5. ✓ Reference original code cited (if porting)