Create monorepo build orchestration and documentation (pnpm workspaces guide)

[Lakes41]

Background

The GuildPass monorepo uses pnpm workspaces across 9 packages (contracts, env, integration-client, webhook-utils, docs, discord-bot, access-api, dashboard, and potentially mobile). Recent build failures reveal gaps in build orchestration, dependency management, and shared configuration. Clear documentation and tooling would prevent misconfigurations and speed up onboarding.

Problem

1. No build orchestration docs: No clear guide on the intended build order, dependency resolution, or parallel vs. sequential execution
2. Ambiguous package roles: It's unclear which packages are libraries, which are applications, and how they depend on each other
3. No troubleshooting guide: When builds fail (as they have), developers lack a runbook
4. No CI/CD specification: The pnpm monorepo setup may not align with GitHub Actions workflows

Expected Outcome

• Clear monorepo documentation explaining structure, build flow, and package dependencies
• Build orchestration defined (what builds in what order, parallelization strategy)
• Troubleshooting guide for common failures
• Automated validation (e.g., GitHub Actions checking workspace integrity)
• Developer quick-start guide for local setup and builds

Suggested Implementation

1. Create MONOREPO.md in the workspace root:

   # GuildPass Monorepo Structure
   
   ## Overview
   - **Packages**: Reusable libraries and shared utilities
     - `packages/contracts`: TypeScript types for on-chain interfaces
     - `packages/env`: Environment configuration schema validation
     - `packages/integration-client`: Web3 integration client
     - `packages/webhook-utils`: Webhook utilities
   - **Apps**: Consumer applications
     - `apps/docs`: Docusaurus documentation
     - `apps/dashboard`: Next.js 14 dashboard
     - `apps/access-api`: Fastify API server
     - `apps/discord-bot`: Discord bot service
     - `apps/mobile`: Expo/React Native mobile app (optional)
   
   ## Build Order
   1. `packages/` (independent libraries, no app dependencies)
      - `packages/contracts` → `packages/env` → `packages/integration-client`, `packages/webhook-utils`
   2. `apps/` (depend on packages)
      - `apps/docs`, `apps/dashboard`, `apps/access-api`, `apps/discord-bot` (parallel)
   
   ## Commands
   - `pnpm install`: Install all dependencies
   - `pnpm build`: Build all packages and apps
   - `pnpm build -r --filter @guildpass/env`: Build specific package
   - `pnpm typecheck`: Type-check all packages
   - `pnpm lint`: Lint all code
   - `pnpm -r dev`: Run all apps in dev mode (if configured)
   
   ## Troubleshooting
   See TROUBLESHOOTING.md

2. Create TROUBLESHOOTING.md:

   # Build Troubleshooting
   
   ## Error: "Module not found: Can't resolve './schemas/dashboard.js'"
   **Cause**: `packages/env` did not emit `.js` files.
   **Fix**:
   1. Check `packages/env/tsconfig.json` for `outDir` and `emitDeclarationOnly` settings
   2. Run `pnpm build -r --filter @guildpass/env`
   3. Verify `packages/env/dist/` contains `.js` and `.d.ts` files
   4. Run `pnpm -r build` again
   
   ## Error: "error TS5042: Option 'project' cannot be mixed with source files"
   **Cause**: Build script contains malformed arguments.
   **Fix**:
   1. Check the package's `package.json` `build` script
   2. Ensure it contains only `tsc -p tsconfig.json` (no extra commands)
   3. Remove any appended `pnpm start`, `pnpm typecheck`, `pnpm lint`, etc.

3. Create a pnpm workspace diagram in ARCHITECTURE.md showing package dependencies:

   # Architecture
   

   packages/contracts (types)
   ↓
   packages/env (validation)
   ↓
   packages/integration-client (Web3 SDK)
   ↓
   packages/webhook-utils (utilities)
   ↓
   apps/* (dashboard, api, bot, docs)

   
   No circular dependencies expected.
   

4. Add .github/workflows/monorepo-ci.yml (or update existing CI):

   name: Monorepo CI
   on: [push, pull_request]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v3
         - uses: pnpm/action-setup@v2
         - uses: actions/setup-node@v3
           with:
             node-version: 18
             cache: 'pnpm'
         - run: pnpm install
         - run: pnpm -r build
         - run: pnpm -r typecheck
         - run: pnpm lint

5. Add workspace validation script in scripts/validate-workspace.js:

   // Check all packages have required fields in package.json
   // Verify no circular dependencies
   // Ensure all tsconfig.json files extend base config

Acceptance Criteria

• MONOREPO.md documents structure, build order, and key commands
• TROUBLESHOOTING.md includes solutions for recent build failures
• ARCHITECTURE.md shows package dependency graph
• CI/CD workflow validates monorepo integrity on every push
• New contributors can set up and build the repo following the guide
• Build failures are traceable to specific package or configuration issues

Affected Files/Directories

• MONOREPO.md (create)
• TROUBLESHOOTING.md (create)
• ARCHITECTURE.md (create)
• .github/workflows/monorepo-ci.yml (create or update)
• scripts/validate-workspace.js (create)
• README.md (update with link to monorepo guide)

[zinodict121]

I would like to work on this issue

[OZILSOLAR]

Hi team!!!!
I would like to work on this issue!!!!!

[ignaciojulio]

Hi @Adamantine-guild team,
I’d be glad to take ownership of this issue and help streamline the GuildPass monorepo orchestration.

I have extensive experience designing and maintaining TypeScript/Node.js monorepos with pnpm workspaces, optimizing multi-package build pipelines, and implementing strict CI/CD quality gates using GitHub Actions.

Proposed Implementation Plan:
1 Monorepo Architecture & Build Flow (MONOREPO.md, ARCHITECTURE.md):
- Document package boundaries: internal libraries (packages/) vs. consumer apps (apps/).
- Define explicit build ordering and parallelization strategies (pnpm --filter ...) to avoid dependency failures.
- Provide a dependency graph ensuring no circular references.
2 Runbook & Developer Experience (TROUBLESHOOTING.md, README.md):
- Create a runbook covering common failure modes (e.g., TS build collisions like TS5042, missing dist/ outputs, cross-package resolution).
- Update onboarding docs for smooth contributor setup.
3 Automated Workspace Validation (scripts/validate-workspace.js):
- Build a validation script to check tsconfig.json references, detect circular dependencies, and enforce consistent package scripts.
4 CI/CD Pipeline Alignment (.github/workflows/monorepo-ci.yml):
- Implement a cached pnpm workflow to validate build, typecheck, and lint deterministically on every PR.

I’m ready to start immediately and deliver a clean, well-tested PR that meets all acceptance criteria.

[grantfox-oss]

🦊 GrantFox — @zinodict121 has been assigned to this issue as part of the Third Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #340)
2. Your PR will be reviewed by the Adamantine-guild maintainers

Good luck! Track your progress on GrantFox.