Start Here

Getting started with GrantMaster engineering

Onboard as a GrantMaster engineer in 30 minutes, learn the architecture guardrails, and find your next deep-dive docs.

First 30 minutes

Get oriented to GrantMaster so you can make safe changes quickly and understand how your work fits into the system.

Code is truth. Treat these docs as a map to the codebase, not a replacement. Always confirm behavior in the relevant files before making changes.

Skim the architecture overview

Read the Architecture overview.
Focus on how multi-tenancy, the service layer (BaseService), and the EventBus fit together.
Note the data layer helpers in src/core/firestoreCollections.ts for when you need to work with Firestore collections.

By the end, you should know where requests enter, where business logic lives, and how events flow through the system.

Learn core domain terms

Open the Glossary.
Identify key concepts you will touch first (for example, agents in src/features/agents/, entitlement config in src/config/entitlements.ts, impact features in src/features/impact/).
Map glossary entries to their referenced files so you know where to look when questions come up.

Use the glossary as your first stop when terminology is unclear.

Set up your environment

Follow Environment setup end-to-end.
Confirm you can run the app and exercise flows relevant to your team.
Keep an eye on logs and Firestore data to see how organizationId propagates through requests.

Success here means you can run the system locally and observe real requests flowing through the architecture you just reviewed.

Ship a safe first change

Work through the Quickstart to make a scoped, low-risk change.
As you edit code, locate the surrounding service classes, Firestore helpers, and any EventBus usage that your change touches.
Verify that your change respects multi-tenancy and existing guardrails before opening a pull request.

Aim for a small win: a change you understand end-to-end, from request to persistence and events.

Core engineering guardrails

Apply these guardrails every time you touch GrantMaster code.

Violating these patterns can break tenancy isolation, auditability, or resilience. If a change feels like it is working around them, pause and get a review from someone familiar with the architecture.

Always enforce multi-tenancy via organizationId.
Every tenant-visible operation must carry an organizationId all the way through: stored in root Firestore collections, enforced by Security Rules, and passed through OrganizationContext. Never query or write cross-tenant data without an explicit, validated organizationId.
Let Security Rules, BaseService, and OrganizationContext do the enforcement.
Use the existing Security Rules and BaseService patterns instead of ad-hoc checks. BaseService and the surrounding service layer centralize validation (via Zod), tenancy, and audit hooks. When in doubt, add logic to the service layer, not to controllers or UI code.
Go through the service layer, not direct Firestore access.
When you need data, look for an existing service or create a new one that extends BaseService. Use the shared Firestore helpers in src/core/firestoreCollections.ts rather than constructing collection paths yourself. This keeps schemas, organizationId handling, and auditability consistent.
Use the EventBus for decoupling cross-cutting behavior.
When a change needs to trigger follow-up work (notifications, indexing, metrics), publish an event on the EventBus instead of calling downstream services directly. Critical events should be persisted to the Firestore systemEvents collection so they can be replayed or audited.
Keep multi-tenancy and side effects out of UI and edge handlers.
UI layers and request handlers should extract context (including organizationId) and delegate to services. They should not make raw Firestore calls or orchestrate complex workflows. Push complexity down into the service layer and event handlers.

Docs hygiene expectations

Set expectations for how you use and maintain these docs as an engineer.

Modular docs with cross-links keep the system understandable as it grows. When you add a new feature or capability, add or update a focused doc page and link it from the architecture or glossary instead of duplicating explanations.

Reflect real behavior.
If you notice a doc that no longer matches the code, update it as part of the same change. Do not leave known inaccuracies for later.
Prefer deep links to source.
When you reference behavior, link to the relevant file (for example, src/features/agents/, geminiService.ts, ragService.ts, src/config/entitlements.ts, src/features/impact/) so future readers can verify details quickly.
Avoid placeholders.
If something is not implemented or is experimental, say so explicitly instead of using filler sections. Mark follow-up work clearly so it does not get mistaken for current behavior.

Next reads

Use these next to understand how your changes deploy and how the system behaves under stress.

Deployment and infrastructure

Disaster recovery

Was this page helpful?

Last updated Mar 1, 2026

Built with Documentation.AI