Src

This directory contains all source code for the business municipality lookup application, organized following Clean Architecture and Hexagonal Architecture prin

Source Code (`src/`)

This directory contains all source code for the business municipality lookup application, organized following Clean Architecture and Hexagonal Architecture principles.

Architecture Overview

The codebase is structured into clear layers with explicit dependencies flowing inward toward the domain:

Dependency Rule: Dependencies flow inward. Domain code never imports from adapters or UI.

Directory Structure

app/ - Next.js 15 App Router pages, API routes, and server actions
components/ - React components organized by feature
adapters/ - Implementations of external service integrations (cache, HTTP, NJ Geocoding API)
domain/ - Pure business logic with no external dependencies
lib/ - Shared utilities (validation, logging, configuration, type factories)
i18n/ - Internationalization configuration (next-intl)
locales/ - Translation JSON files for supported languages
__tests__/ - Test helpers, fixtures, and quality checks

Key Principles

Dependency Rule: Dependencies only point inward. Domain code never imports from adapters or UI.
Port & Adapter Pattern: Domain defines interfaces (ports), adapters implement them.
Dependency Injection: Adapters are injected into use cases, not imported directly.
Type Safety: TypeScript types with branded types for domain primitives.
Testability: Pure functions and dependency injection enable isolated unit testing.

Technology Stack

Runtime: Bun v1.3.5
Framework: Next.js v16 with App Router
Language: TypeScript
Styling: Tailwind CSS v4
Testing: Bun test runner with 99.97% code coverage
Geocoding: NJ Office of GIS geocoding API

Getting Started

Each subdirectory contains its own README with specific documentation. Start with:

domain/README.md - Understanding core business logic
adapters/README.md - External service integrations
components/README.md - UI component library
app/README.md - Route structure and pages

Src