How sebas0811buitrago/port-adapters-architecture works
Project Type and Purpose
• This is a learning monorepo demonstrating the Port-Adapters (Hexagonal) pattern across multiple mini-applications:
• Book Search
• BMI Calculator
• AI SDK utilities
• Framework demos (Next.js, Vanilla JS)
• Each app comes in several flavors: “Without Architecture” (monolithic), “With Architecture” (clean ports/adapters), and “Screaming Architecture” (feature-based).
File Structure
• Top-level folders correspond to variants:
• scripts-without-architecture/
• scripts-with-architecture/
• with-screaming-architecture/
• without-screaming-architecture/
• complete-architecture-next.js/
• vanilla-js-with-architecture/
• vanilla-js-without-architecture/
• ai-sdk/
• Within each:
• domain/ or src/modules/<feature>/domain – core business objects & rules
• service/ or src/modules/<feature>/service – use-case implementations
• ui/, cli/, api/, mcp/ – adapters for different interfaces
• shared/ or lib/ – cross-cutting utilities
• config files & package.json – build and deployment info
README Insights
• Confirms two main sample applications (Book Search & BMI Calculator), plus an AI SDK demonstrating embeddings, text generation, etc.
• Emphasizes separation of domain vs. interface, swap-in/out adapters, and testability.
Main Components
a. Domain Core
• BookSearchDomain
• BMICalculatorDomain
• AI-SDK Domain functions (embeddings, prompts, streaming)
b. Ports (Interfaces)
• e.g. BookRepositoryPort, BMICalculatorPort, AIModelPort
c. Adapters
• CLI Adapter (scripts/cli)
• API Adapter (scripts/api, Next.js API routes)
• MCP Adapter (scripts/mcp)
• UI Adapter (React components in Next.js, Vanilla-JS UI)
d. External Dependencies
• JSON data store (bmi-records.json)
• External book APIs
• Local or cloud AI models (via ai-sdk)
e. Shared Utilities
• Conversion helpers, HTTP clients, logging, test setups
Relationships & Data Flows
• Adapters → invoke Ports → Domain Core → may call out to Services/External → return data back → Adapter → render or respond.
• Example for BMI API:
API Route → BMICalculatorPort → BMICore → write/read JSON store → respond JSON.
• Example for Book Search UI:
React Component → BookSearchPort → Domain → HTTP call to external book API → return list → UI render.
Architectural Patterns & Principles
• Use ports as the boundary interfaces (thin lines between core and adapters).
• For “Screaming Architecture,” group by feature modules rather than technical layers.
Putting It All Together
• Surround each with their adapters; connect to data stores or external APIs.
• Below that, separate three columns showing the three architectural approaches to the same functionality.