Local Development Setup

Relevant source files

The following files were used as context for generating this wiki page:

• GEMINI.md
• README.md
• web/package.json
• scripts/sentry-setup-automation.sh
• scripts/test-observability.sh
• [design-system/HEX-YT-INTEL Design System (1)/README.md](https://github.com/Hex-Tech-Lab/hex-yt-intel/blob/2cca14edaf01ee2f92498e26c84151ce7dcccd5f/design-system/HEX-YT-INTEL Design System (1)/README.md)

Local development for the HEX-YT-INTEL project is centered around a Hybrid Edge Symphony architecture, which integrates a Next.js frontend with high-performance streaming engines. The setup requires specific Node.js and package management versions to ensure compatibility with the Edge Runtime and to maintain a high production bundle compression ratio.

The project follows a Hexagonal Lite (Ports & Adapters) and Domain-Driven Design (DDD) pattern. This structure separates core business logic (Domain Services) from infrastructure connectors (Adapters), allowing for consistent development across local and edge environments.

Sources: README.md:17-25, GEMINI.md:17-25, GEMINI.md:162-180

Prerequisites and Environment

The project enforces a strict set of versions for the runtime and package management to ensure a "Known Good State" across development environments.

Core Dependencies

Requirement	Version	Notes
Node.js	24.16.0 LTS	Strictly pinned for CI/deployment
pnpm	11.1.3	Required for workspace isolation
Next.js	16.2.6	Locked
TypeScript	6.0.3	High-performance type checking
Zustand	5.0.13	Aligned with Zod for state
Zod	4.4.3	Aligned with Zustand for validation

Sources: GEMINI.md:17-25, web/package.json:60-62, web/package.json:81

Banned Dependencies

To maintain an 89% production bundle compression ratio and ensure Edge Runtime compatibility, the following are strictly prohibited:

• Material-UI (@mui/material)
• Emotion styling (@emotion/react, @emotion/styled)
• Runtime CSS-in-JS injection engines
• next-auth (Supabase getSupabaseClientWithAuth() is used instead)

Sources: GEMINI.md:27-36

Initial Repository Setup

The project uses a monorepo-style structure where the web dashboard and high-performance workers are separated.

Setup Flow

The following diagram illustrates the sequence for initializing the local environment:

Environment Configuration

Key environment variables must be defined in web/.env.local. These include Supabase credentials and observability tokens. Automation scripts like sentry-setup-automation.sh are provided to sync these variables between the local environment and Vercel.

# Example update via automation script
if grep -q "NEXT_PUBLIC_SENTRY_DSN" .env.local; then
  sed -i "s|^NEXT_PUBLIC_SENTRY_DSN=.*|NEXT_PUBLIC_SENTRY_DSN=${SENTRY_DSN}|" .env.local
else
  echo "NEXT_PUBLIC_SENTRY_DSN=${SENTRY_DSN}" >> .env.local
fi

Sources: scripts/sentry-setup-automation.sh:66-74

Observability and Monitoring Setup

A critical part of local setup is ensuring that observability tools are correctly configured to monitor high-latency LLM synthesis.

Sentry Integration

Sentry must be initialized to track both frontend errors and performance metrics. This is handled via sentry.config.js and automated setup scripts that wrap the Next.js configuration.

Verification Scripts

Developers should use scripts/test-observability.sh to verify the local setup:

• Health Check: Tests /api/health for structured 200 responses.
• Config Check: Verifies existence of sentry.config.js and metrics.ts.
• Instrumentation: Ensures web/instrumentation.ts is correctly placed for Next.js 16.

Sources: scripts/test-observability.sh:35-50, scripts/test-observability.sh:150-160

Development Workflow and Laws

The repository enforces "Core Laws" and a "Preflight Mandate" to prevent multi-agent pollution and maintain code quality.

Pre-Execution Confirmation

Before any code mutation, developers (or agents) must execute a local preflight check:

1. Check Agent Ledger: Read .memory/AGENT_LEDGER.md for active tasks.
2. Verify State: Run git status and git diff to ensure no overlapping fixes.
3. Validate Build: Run pnpm build --dry-run to verify the issue persists before applying a fix.

Sources: GEMINI.md:73-90

Root Directory Constraints

The repository root is restricted to a maximum of 4 Markdown files to prevent clutter:

1. CLAUDE.md (Infrastructure)
2. GEMINI.md (Coordination)
3. README.md (General Info)
4. AGENTS.md (Agent Identities)

All other documentation must live within the /docs/ sub-directories.

Sources: GEMINI.md:38-42, GEMINI.md:46-56

Summary

Local development in HEX-YT-INTEL requires strict adherence to Node.js 24.16.0 and pnpm 11.1.3. The setup is highly automated through shell scripts for observability and preflight validation. By following the Hex-Lite architecture and maintaining root file constraints, the environment remains optimized for high-performance edge streaming and AI synthesis.