Onboarding Guide — Welcome to Forma3D.Connect¶

Version: 1.0 Date: March 19, 2026 Status: Active Audience: New team members (developers, designers, product)

Welcome to the team! This guide is your map through the Forma3D.Connect documentation and codebase. It tells you what to read, in what order, and why — so you can go from zero to productive in about three days.

The Documentation Map¶

The documentation is organized in numbered folders (00–10). The diagram below shows how they relate and the recommended reading flow:

Your Onboarding Journey¶

The journey is split into five stages. Each builds on the previous one. Follow the numbered path:

Stage 1: Understand the Business (Day 1 Morning)¶

Goal: Understand what Forma3D.Connect is, why it exists, and who it serves.

Reading List¶

Key Concepts to Grasp¶

Stage 2: Explore the Architecture (Day 1 Afternoon)¶

Goal: Understand how the system is built — services, data flows, events, patterns.

Reading List¶

System at a Glance¶

Stage 3: Set Up Your Environment (Day 2 Morning)¶

Goal: Get the application running locally on your machine.

Reading List¶

Verification Checklist¶

• curl http://localhost:3000/health returns {"status":"ok"}
• Swagger UI loads at http://localhost:3000/api/docs
• React dashboard loads at http://localhost:4200
• Prisma Studio opens at http://localhost:5555
• pnpm test runs without failures

Stage 4: Learn How We Work (Day 2 Afternoon)¶

Goal: Understand the development workflow, branching strategy, and how features go from idea to production.

Reading List¶

AI-First Development: How Features Are Built¶

This project uses an AI-assisted development model. Most features follow a three-step pattern:

See feature-implementation.md for the full flow with diagrams.

Stage 5: Go Deep & Contribute (Day 3+)¶

Goal: Build deeper knowledge in your area and make your first contribution.

Reading List by Role¶

All Roles¶

Backend Developers¶

Frontend Developers¶

DevOps / Infrastructure¶

Product / Design¶

The Complete Reading Path¶

One diagram showing the full recommended reading order across all five stages:

Quick Reference: Where to Find What¶

Live Resources¶

Day 1–3 Checklist¶

Day 1¶

• Read the documentation index (docs/README.md)
• Read the vision document — understand the "why"
• Read the requirements — understand the "what"
• Read the strategy — understand the "where"
• Read the architecture overview — understand the "how"
• Browse the technology stack
• Look at C4 Context and Container diagrams
• Skim the patterns catalog
• Skim ADR titles (deep-read the ones relevant to your area)

Day 2¶

• Set up your local development environment
• Get the application running (pnpm dev)
• Verify health endpoints, Swagger UI, and React dashboard
• Run the test suite (pnpm test)
• Read the trunk-based development workflow
• Read how features are implemented (research → prompt → loop)
• Read the implementation plan — know what phase we're in
• Browse the CI/CD pipeline reference

Day 3+¶

• Read the user manual — use the app as an operator would
• Browse EventCatalog (live or local) — explore domains and events
• Read crash courses for your stack (React and/or NestJS)
• Deep-dive into sequence diagrams and state machines
• Explore the codebase: apps/ for services, libs/ for shared code, prisma/ for schema
• Pick up your first task

The Codebase at a Glance¶

Tips for Your First Week¶

1. Use Swagger UI (/api/docs) to explore the API interactively — it's the fastest way to understand endpoints and payloads.
2. Use Prisma Studio (pnpm db:studio) to browse the database visually.
3. Browse EventCatalog to understand how services communicate — every BullMQ event, HTTP command, and query is documented with schemas.
4. Read ADRs when you ask "why?" — if you wonder why something is built a certain way, there's likely an ADR for it.
5. PlantUML is everywhere — install the VS Code extension and press Alt+D on any .puml file to see diagrams. Inline PlantUML in Markdown renders in Zensical and via pandoc.
6. Set up EventCatalog MCP — Cursor can query the EventCatalog via an MCP server. See environment-setup.md for setup instructions. Once configured, you can ask questions like "What events does the Order Service publish?" directly in the IDE.

Forma3D.Connect | Onboarding Guide