Skip to main content

Contributing to iAm

Thank you for your interest in contributing to iAm. This guide covers the development workflow, conventions, and process for submitting changes.

Getting Started​

  1. Fork the repository on GitHub
  2. Clone your fork locally
  3. Install dependencies: yarn install
  4. Set up your environment following the Installation Guide
  5. Create a feature branch: git checkout -b feature/your-feature-name

Development Workflow​

1. Understand Requirements​

Before writing code, make sure you understand:

  • The consciousness measurement context (see Core Concepts)
  • How the change fits into the graph architecture
  • Whether GraphQL schema changes are needed

2. Check Existing Patterns​

Always look for existing components and patterns before implementing something new:

  • Check neighboring code for conventions
  • Look for existing UI components in client/src/components/
  • Review existing resource patterns in server/src/resources/

3. Implement​

Follow the patterns documented in Development Standards:

  • Use the resource structure for new server entities
  • Use tailwind-styled-components for new UI components
  • Follow naming conventions consistently

4. Update GraphQL Types (if applicable)​

If you modified any GraphQL models, inputs, or outputs:

cd server && yarn build:types:all

This can take 1-2 minutes. Do not create temporary types while waiting.

5. Write Tests​

  • Client components: Vitest + React Testing Library
  • Server services: Jest
  • End-to-end: Playwright

6. Build and Verify​

yarn build        # Must pass
yarn typecheck    # Must pass
yarn format       # Format code

7. Test Thoroughly​

cd client && yarn test          # Unit tests
cd server && yarn test:e2e      # Server E2E
cd client && yarn test:e2e      # Client E2E

Code Style​

Do​

  • Use TypeScript strictly -- avoid any types
  • Import types from their source (never duplicate type definitions)
  • Use @Measure decorators on service methods
  • Follow existing naming conventions
  • Use yarn for all package management
  • Extend utility output classes from resources/utils/outputs/classes.ts

Don't​

  • Use as any without explicit permission
  • Use @Field(() => Date) in TypeGraphQL (use GraphQLDateTime from graphql-scalars)
  • Use raw model classes in output types (use Output classes)
  • Use npm (use yarn)
  • Use MUI components unless explicitly asked
  • Create Storybook stories

Submitting Changes​

Pull Request Process​

  1. Ensure your branch is up to date with main
  2. Push your feature branch to your fork
  3. Create a Pull Request against main
  4. Fill out the PR template with:
    • Summary of changes
    • Testing performed
    • Screenshots (for UI changes)
  5. Wait for review and address feedback

Commit Messages​

Write clear, descriptive commit messages that explain the "why" behind changes:

Add verbal thought tracking session type

Implements the core session type for CRAWL study protocol,
supporting real-time verbal thought capture with valence
(positive/negative/neutral) classification via button input.

PR Guidelines​

  • Keep PRs focused on a single feature or fix
  • Include tests for new functionality
  • Update documentation if behavior changes
  • Ensure the build passes before requesting review

Project Structure Reference​

iAm/
├── client/              # React frontend
│   ├── src/pages/       # Route-based pages
│   ├── src/components/  # Reusable UI components
│   ├── src/context/     # React Context providers
│   └── src/queries/     # Apollo GraphQL queries
├── server/              # GraphQL API
│   ├── src/resources/   # Domain entities
│   ├── src/server/      # Server configuration
│   └── src/services/    # External integrations
├── common/              # Shared types
└── docs/                # Documentation

Questions?​

License​

By contributing to iAm, you agree that your contributions will be licensed under the AGPL-3.0 License.