Directional Sentiment

A Next.js 15 application built with TypeScript, implementing hexagonal architecture patterns with clear separation between domain logic and infrastructure concerns.

Quick Start for New Developers

Prerequisites

• Node.js 18+ - JavaScript runtime
• pnpm - Package manager (specified in packageManager field)
• corepack - Enable with corepack enable for automatic pnpm version management

Environment Setup

1. Copy environment template:

   cp .env.example .env.local

2. Configure Supabase (optional for basic development):

   • Get your project URL and anon key from Supabase Dashboard
   • Update .env.local with your values:

     NEXT_PUBLIC_SUPABASE_URL=https://your-project-id.supabase.co
     NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here

Installation & First Run

# Enable pnpm if not already done
corepack enable

# Install dependencies
pnpm install

# Start development server with Turbopack
pnpm dev

Open http://localhost:3000 to see the application.

Key Entry Points for Code Exploration

Start exploring the codebase with these key files:

• src/app/(public)/page.tsx - Main landing page component
• src/app/_domain/ - Pure domain logic (business rules, entities, use cases)
• src/app/(adapters)/ - Infrastructure implementations (database, APIs)
• src/app/_config/env.ts - Environment variable configuration and validation
• src/middleware.ts - Request middleware composition

Essential Development Commands

pnpm dev                # Development server with hot reload
pnpm test:unit:jest     # Run unit tests
pnpm build              # Production build
pnpm lint               # Check code style and errors

Architecture

This project follows hexagonal (ports & adapters) architecture with:

• Domain Layer (_domain/): Pure business logic with no external dependencies
• Adapters ((adapters)/): Infrastructure implementations for databases, APIs, etc.
• Infrastructure (_infra/): Cross-cutting concerns like middleware and configuration

Documentation

Comprehensive development documentation is available in the .github directory:

• Architecture Guidelines - Hexagonal architecture patterns, domain structure, and data flow
• Testing Guidelines - Unit testing methodology and API testing patterns
• Code Conventions - Code style, naming, and commit message formats
• Tech Stack Details - Dependencies, frameworks, and tool-specific guidance
• Database - Schema notes, access patterns, and Supabase usage
• AI Assistant Instructions - Project-specific guidance for AI coding assistants
• AGENTS.md - Canonical agent behavior, scope, and precedence
• INSTRUCTION-TIPS.md - General tips for writing effective instructions

Sequence Diagrams

All sequence diagrams are located in .github/sequence-diagrams/.

Learn More

• Next.js Documentation - Learn about Next.js features and API
• Supabase Documentation - Database and authentication platform
• Tailwind CSS - Utility-first CSS framework