# sebas0811buitrago/port-adapters-architecture architecture

> Architecture diagram of the GitHub repository sebas0811buitrago/port-adapters-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sebas0811buitrago/port-adapters-architecture
- Repository: https://github.com/sebas0811buitrago/port-adapters-architecture

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Book Search Hexagon
    subgraph "Book Search"
        direction TB
        BSDomain["BookSearchDomain"]:::domain
        BookService["BookSearchService"]:::api
        BookUI["BookSearch UI Adapter"]:::ui
        ExternalBookAPI["External Book API"]:::external
    end

    %% BMI Calculator Hexagon
    subgraph "BMI Calculator"
        direction TB
        BMIDomain["BMICalculatorDomain"]:::domain
        BMICLI["BMI CLI Adapter"]:::cli
        BMIApi["BMI API Adapter"]:::api
        BMIMCP["BMI MCP Adapter"]:::mcp
        JSONStore["bmi-records.json"]:::external
    end

    %% AI-SDK Hexagon
    subgraph "AI SDK"
        direction TB
        AISDK["AI-SDK Core Functions"]:::domain
        Embeddings["Embeddings Module"]:::api
        Prompt["Prompt Generation"]:::api
        Streaming["Streaming Objects"]:::api
        ExternalLLM["External LLM Service"]:::external
    end

    %% Connections Book Search
    BookUI -->|"invoke Port"| BSDomain
    BookService -->|"invoke Port"| BSDomain
    BSDomain -->|"calls External"| ExternalBookAPI

    %% Connections BMI
    BMICLI -->|"invoke Port"| BMIDomain
    BMIApi -->|"invoke Port"| BMIDomain
    BMIMCP -->|"invoke Port"| BMIDomain
    BMIDomain -->|"read/write"| JSONStore

    %% Connections AI-SDK
    Embeddings -->|"invoke"| AISDK
    Prompt -->|"invoke"| AISDK
    Streaming -->|"invoke"| AISDK
    AISDK -->|"call"| ExternalLLM

    %% Click Events
    click BSDomain "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/complete-architecture-next.js/src/modules/search-books/domain/Book.ts"
    click BookService "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/complete-architecture-next.js/src/modules/search-books/service/getBooksOption1.ts"
    click BookUI "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/complete-architecture-next.js/src/modules/search-books/components/book-searcher.tsx"
    click BMIDomain "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/scripts-with-architecture/bmi/domain/bmi.ts"
    click BMICLI "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/scripts-with-architecture/bmi/cli/bmi-calculator.ts"
    click BMIApi "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/scripts-with-architecture/bmi/api/server.ts"
    click BMIMCP "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/scripts-with-architecture/bmi/mcp/client.ts"
    click AISDK "https://github.com/sebas0811buitrago/port-adapters-architecture/blob/main/ai-sdk/src/embeddings.ts"

    %% Styles
    classDef domain fill:#FFD700,stroke:#333,stroke-width:2px;
    classDef ui fill:#1E90FF,stroke:#333,stroke-width:2px;
    classDef api fill:#32CD32,stroke:#333,stroke-width:2px;
    classDef cli fill:#FFA500,stroke:#333,stroke-width:2px;
    classDef mcp fill:#9370DB,stroke:#333,stroke-width:2px;
    classDef external fill:#C0C0C0,stroke:#333,stroke-width:2px;
```
