Imported from seandearnaley/brainstrike-typescript-starter (AGENTS.md). Install upstream with npx skills add seandearnaley/brainstrike-typescript-starter. Copyright stays with the author.

Contributor Guide for AI Agents and Developers

Welcome to the brainstrike-typescript-starter monorepo! This guide is designed to help both human developers and AI agents understand how to effectively contribute to this project.

Codebase Overview

This is a pnpm workspace-powered monorepo using pnpm as the package manager. The structure is as follows:

client/: The React + TypeScript client application (brainstrike-client).
- Built with Vite, React 19+, Material UI, and Apollo Client 3.0
- Uses GraphQL Code Generator for type-safe hooks and operations
- Testing with Vitest and React Testing Library
server/: The Node.js + TypeScript GraphQL API server (brainstrike-server).
- Built with Apollo Server, Express, and TypeORM
- PostgreSQL database with migration support
- Comprehensive testing with Vitest
- GraphQL Code Generator for resolvers and types

Development Environment & Tips

Node.js: Use Node.js version 18.19.1 or higher (as specified in package.json engines).
Package Manager: This project uses pnpm. Install dependencies from the root of the monorepo:
```
pnpm install
```
Running Development Servers/Tasks: Use pnpm workspace commands to run scripts.
- To run both client and server in development mode:
```
pnpm dev
```
- To run only the client:
```
pnpm dev:client
```
- To run only the server:
```
pnpm dev:server
```
- To build all packages:
```
pnpm build
```
- To build a specific package:
```
pnpm build:client
# or
pnpm build:server
```

Adding Dependencies:

To add a dependency to the client:

pnpm add <package-name> --filter brainstrike-client

To add a dependency to the server:

pnpm add <package-name> --filter brainstrike-server

To add a dev dependency to the root workspace:
```
pnpm add -D <package-name> -w
```

Package Names:
- Client: brainstrike-client
- Server: brainstrike-server
- Root: brainstrike-monorepo

Contribution and Style Guidelines

Primary Language: TypeScript. Adhere to strict mode.
Client Framework: React 19+ with functional components and hooks, Material UI for components.
Server Framework: Apollo Server with Express, TypeORM for database access.
Database: PostgreSQL with TypeORM migrations.
Styling: Material UI components and Emotion for styling.
State Management: Apollo Client for GraphQL state management.
Linting & Formatting: ESLint and Prettier are used for linting and formatting.
- Check for issues:
```
pnpm lint
```
- Auto-fix simple problems (recommended before committing): bash pnpm lint:fix These commands run across both client and server workspaces. Ensure your code is compliant before committing.
File & Directory Naming:
- General: kebab-case for files and directories (e.g., my-feature/, utility-functions.ts).
- React Components: PascalCase for component files (e.g., CardList.tsx, UserProfile.tsx), and PascalCase for component exports.
- Custom Hooks: camelCase starting with use (e.g., useCardData.ts, useAuth.ts).
Commit Messages: Follow Conventional Commits specification.
- Format: <type>(<scope>): <subject>
- Types: feat, fix, docs, style, refactor, test, chore, ci, perf, build, revert.
- Scopes: client, server, api, ui, config, deps, core, test, types, security, db.

Testing Instructions

Frameworks:
- Vitest: For unit and integration tests (.test.ts, .integration.test.ts).
- React Testing Library: For React component testing.

Running Tests:

Unit & Integration Tests (Vitest):

Run all tests across both client and server:
```
pnpm test
```
Run tests for a specific workspace:
```
pnpm test:client
# or
pnpm test:server
```

Run tests in watch mode for a specific workspace:

pnpm --filter brainstrike-client test:watch
# or
pnpm --filter brainstrike-server test:watch

From within a package's directory, you can run its specific test script:

cd client
pnpm test # Runs Vitest for the client

cd server
pnpm test # Runs Vitest for the server

Test Location: Tests should be co-located with the source files they are testing (e.g., my-component.tsx and my-component.test.tsx in the same directory).
Type Checking: Ensure there are no TypeScript errors.
```
pnpm typecheck
```
This command runs TypeScript type checking across both workspaces.
CI Pipeline: The Continuous Integration setup can be found in .github/workflows/.
Requirement: All tests (unit, integration) and type checks must pass. New code or changes must include corresponding tests. Fix any errors until the entire suite is green.

Database Setup

Database: PostgreSQL is required. Docker Compose is provided for local development.
Migrations: Use TypeORM migrations for database schema changes.
- Run migrations:
```
pnpm --filter brainstrike-server migrate:up
```
- Rollback migrations:
```
pnpm --filter brainstrike-server migrate:down
```
Test Database: A separate test database (brainstrike_test) is used for testing.

GraphQL Development

Code Generation: Both client and server use GraphQL Code Generator.

Generate types and hooks for client:

pnpm --filter brainstrike-client generate

Generate types and resolvers for server:

pnpm --filter brainstrike-server generate

Watch mode for development:

pnpm --filter brainstrike-client generate:dev
# or
pnpm --filter brainstrike-server generate:dev

Pull Request (PR) Instructions

Title Format: Use the Conventional Commits format for PR titles: <type>(<scope>): <Descriptive PR Title> Example: feat(client): Add user profile page or fix(server): Resolve database connection issue
Checklist:
- Crucially, the entire following command chain must pass without errors:
```
pnpm install && pnpm lint && pnpm build && pnpm typecheck && pnpm test
```
- PR description clearly explains the changes and reasoning.
- New functionality is covered by tests.
- Database migrations are included if schema changes are made.
- GraphQL schema changes are properly generated and tested.

Codebase Migrations & Deprecations

Recent Migration: The project has migrated from Yarn to pnpm workspaces for better performance and modern workspace features.
When deprecating code, follow established deprecation patterns and update documentation accordingly.
Ensure all dependencies are properly managed through the pnpm catalog system defined in pnpm-workspace.yaml.

Validating Changes (Summary)

Before pushing code or opening a PR, ensure the entire following command chain completes successfully:

pnpm install && pnpm lint && pnpm build && pnpm typecheck && pnpm test

This comprehensive check includes:

Dependency Installation: pnpm install (ensures all dependencies are correctly installed).
Linting: pnpm lint (fix any reported issues with pnpm lint:fix).
Building: pnpm build (ensures both client and server build successfully).
Type Checking: pnpm typecheck (resolve all TypeScript errors).
Testing: pnpm test (all unit and integration tests should pass).

Additional validation for database-related changes:

Ensure migrations run successfully: pnpm --filter brainstrike-server migrate:up
Verify GraphQL schema generation: pnpm --filter brainstrike-server generate

Only if this entire sequence is successful is the code considered ready for a Pull Request.

Architecture Notes

The project follows a modern, layered architecture:

Client: React 19+ with Apollo Client for GraphQL state management
Server: Apollo Server with Express and TypeORM for database access
Database: PostgreSQL with TypeORM migrations and entities
Testing: Comprehensive testing with Vitest across both client and server
Type Safety: Full TypeScript coverage with GraphQL Code Generator

By following these guidelines, we can maintain a high-quality, consistent, and efficient development workflow for the brainstrike-typescript-starter project.

brainstrike-typescript-starter

About