Developer Zone: Day 1 Guide

TIP

Quick Start: Run pnpm dev from the root to start the development environment.

Welcome to the HelpMApp codebase. This guide covers the essentials for contributing to the project.

Tech Stack

• Framework: Next.js 15 (App Router) + React 18
• Database: PostgreSQL (Supabase) + Prisma ORM
• Styling: Tailwind CSS + Framer Motion
• State: TanStack Query + IndexedDB (Offline-First)
• Monitoring: Slack (Alerts) + Sentry (Errors)

Project Structure

apps/
├── web/            # Main Next.js application
├── docs/           # Documentation source (VitePress)
├── worker/         # Background job runner
└── public-site/    # [Submodule] helpmapp.github.io
packages/
├── config/         # Shared ESLint/TS config
├── types/          # Shared TypeScript definitions
└── ui/             # Shared React components
prisma/             # Database schema and migrations
scripts/            # The "Nerve Center" automation

Key Commands

Command	Description
pnpm dev	Start development servers
pnpm build	Build all projects
pnpm test:smoke	Run critical E2E tests
pnpm push-and-notify	Push code and alert Slack

Slack Integration

Every developer should have access to the project's Slack workspace. Most automated updates are posted to the #general channel.

• Notifications: Check Slack after running scripts/ to confirm success.
• Test Reports: Playwright results are automatically posted to Slack in CI.

Lead Developer Agent (Gemini CLI)

The project is maintained with the assistance of an automated Lead Developer Agent. If you are interacting via the Gemini CLI, the agent can perform automated data audits, execute hotfixes, and sync documentation.

Contribution Workflow

1. Create a feature branch from staging.
2. Use Conventional Commits (feat:, fix:, docs:).
3. Verify with pnpm test:smoke before pushing.
4. Merge to master for production deployment.