Forward Impact Team

Getting Started: Contributors

Getting Started: Contributors

Set up the Forward Impact monorepo for development. This guide covers installation, data generation, and running the quality checks.

Clone and install

git clone https://github.com/forwardimpact/monorepo.git
cd monorepo
bun install
make quickstart

The quickstart target bootstraps environment files, generates data, runs codegen, and processes resources.

Generate synthetic data

The monorepo includes a synthetic data pipeline for testing and development: 

make synthetic

This uses cached prose from data/synthetic/prose-cache.json and requires no LLM access. It produces framework definitions, organizational documents, and activity data that the products consume during development and testing.

Other generation modes:

make synthetic-update     # Regenerate prose via LLM and update the cache
make synthetic-no-prose   # Structural data only, no prose content

Run checks

Run the full quality suite before committing:

bun run check

This runs formatting (Prettier), linting (ESLint), unit tests (node --test), and data validation (fit-map validate) in sequence.

To auto-fix formatting and lint issues:

bun run check:fix

Understand the structure

products/       Six products (map, pathway, basecamp, guide, summit, landmark)
libraries/      Shared libraries (libskill, libui, libdoc, etc.)
services/       gRPC microservices (agent, graph, llm, memory, etc.)
data/           Generated and framework data
config/         Service and tool configuration
specs/          Feature specifications and plans
website/        Documentation website

Products answer specific questions for specific users. Map defines what good engineering looks like. Pathway renders career frameworks. Basecamp manages personal knowledge. Guide interprets artifacts. Summit models team capability.

Libraries provide shared logic following OO+DI patterns -- classes accept dependencies through constructors, factory functions wire real implementations, tests inject mocks directly.

Services are gRPC microservices supervised by fit-rc. Start them with make rc-start.

Development workflow

  1. Create a branch from main
  2. Make your changes
  3. Run bun run check
  4. Run make audit (npm audit + gitleaks secret scanning)
  5. Commit and push

Commit messages follow conventional format: type(scope): subject. Types include feat, fix, refactor, docs, style, test, chore, and perf. Scope is the package name (e.g., map, libskill, pathway). Add ! after scope for breaking changes.

Next steps