Heritage Community Hub — workspace configuration

Note: This file predates several locked decisions. The stack summary below has been updated to match the accepted ADRs. The /project-management folder referenced in the original was renamed to pmo/. The backend is a containerised Node.js API, not Azure Functions. The package manager is pnpm + Turborepo, not npm.

This is a pnpm monorepo orchestrated by Turborepo (ADR 0001) containing all components of Heritage Community Hub. For a full walkthrough of the structure and rationale, see docs/internal/reference/REPOSITORY_STRATEGY.md and ADR 0001.

Workspace structure

/apps — applications (deployable surfaces)

• web/ — React + TypeScript web client (Vite; served by Azure Static Web Apps)
• api/ — Node.js containerised API (Express or Fastify; deployed to Azure Container Apps — ADR 0024)
• mobile/ — React Native + Expo (iOS and Android — ADR 0002)

/packages — shared libraries (imported by apps; not deployed independently)

• shared-types/ — TypeScript type definitions shared between all apps (single source of truth for API contracts)
• api-client/ — typed SDK; the only way a surface calls the backend API
• shared-utils/ — common validation, formatting, RBAC helpers
• shared-config/ — shared configuration constants
• ui/ — design tokens and shared design system

/infrastructure — infrastructure as code

• Bicep templates for Azure resource deployment (Container Apps, PostgreSQL Flexible Server, Blob Storage, Key Vault, Static Web Apps)

/database — data layer

• Prisma schema (schema.prisma) — canonical data model targeting PostgreSQL (ADR 0024)
• Design schema (schema.sql) — T-SQL design artifact; superseded by Prisma schema in Phase 1
• Migration scripts (Phase 1+)
• Seed data for development and testing

/docs — documentation

• docs/internal/ — team-facing architecture, ADRs, guides, runbooks (Diátaxis-organised)
• docs/member/ — member-facing in-app documentation

/pmo — project and portfolio management

• Platform strategy, epic priority plan, sprint tracking, retrospectives

Development workflow

Important: do not run builds on the planning/documentation VM. See how-to/local-development.md for environment prerequisites and build environment rules.

Getting started

# Clone the repository
git clone https://github.com/Heritage-Virginia/heritage-community-hub.git
cd heritage-community-hub

# Install all workspace dependencies (pnpm reads pnpm-workspace.yaml)
pnpm install

# Start all development servers concurrently (via Turborepo)
pnpm dev

Available scripts

All scripts delegate to Turborepo task graph entries. Run from the repo root:

Script	What it does
pnpm dev	Start all apps in watch mode (Turborepo TUI)
pnpm dev:api	Start apps/api only
pnpm dev:web	Start apps/web only
pnpm build	Build all packages in dependency order
pnpm test	Run all workspace tests
pnpm lint	Lint all code
pnpm run clean	Remove all build artifacts

Why monorepo

• Web, iOS, and Android all share packages/shared-types and packages/api-client — trivial in a monorepo, painful across repos.
• Atomic commits: change an API contract and update all three surfaces in one pull request.
• Small team; one CI config, one dependency graph, one VS Code workspace.
• Mobile's separate release cadence (App Store / Play Store) is handled by a separate pipeline, not a separate repository.

See REPOSITORY_STRATEGY.md for the full rationale and split triggers.