# erazor48/ethan-portfolio architecture

> Architecture diagram of the GitHub repository erazor48/ethan-portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/erazor48/ethan-portfolio
- Repository: https://github.com/erazor48/ethan-portfolio

## Overview

To accurately represent the “Ethan Orain Portfolio – AI Chatbot” system, follow these steps:

##### Project Type and Purpose
- This is a full-stack Next.js web application (React + server-side API) that serves a personal portfolio with:
- A static/dynamic frontend (app pages + React components)
- A backend API (Next.js API routes) providing AI‐driven chat and GitHub‐synchronized data
- External integrations (OpenAI via LangChain, GitHub API)

##### File Structure
- Top-level:
- app/… – Next.js 13 “app router” pages (UI routes and server components)
- app/api/… – serverless API routes: POST/GET /chat, GET/POST /projects
- components/… – React UI components and custom hooks
- lib/… – core data and service layer:
– lib/data/personal-data.ts (in-code database)
– lib/services/*.ts (ChatbotService, GitHubSyncService, ProjectAutomationService, DataService)
– lib/ai (LangChain integrations and tools)
- public/, styles/ – static assets and Tailwind CSS
- next.config.ts, tsconfig.json, package.json – build & tooling

##### Extract Architectural Insights from README
- Four main backend services abstracted in lib/services
- Data flows: GitHub → cache/DataService → frontend & chatbot
- Chatbot uses LangChain (ChatbotService) calling OpenAI
- Project automation auto-manages and caches projects
- Frontend UI components consume data via built-in fetch to API routes

##### Main Components and Their Interactions
a. Frontend Layer
– Next.js React pages (app/…) render UI components (components/)
– ThemeToggle, Navbar, Hero, ProjectCard, ExpandableChatDemo, etc.
– Invokes client-side hooks (useChat) and browser fetch to API

b. API Layer (Backend)
– /api/chat → ChatController → ChatbotService (uses LangChain → OpenAI API) & DataService
– /api/projects → ProjectController → GitHubSyncService & ProjectAutomationService & DataService

c. Service Layer
– DataService: central facade for lib/data and cached GitHub data
– GitHubSyncService: fetches repos via GitHub API → caches in DataService
– ProjectAutomationService: processes, enriches project data
– ChatbotService: builds prompts, invokes LangChain, returns responses

d. Data Layer
– personal-data.ts: static definitions (experience, skills, about)
– GitHub‐fetched data: projects, languages, stats
– Cache mechanism (in-memory or file/cache store) managed by services

e. External Systems
– OpenAI API (via LangChain)
– GitHub REST API

##### Architectural Patterns & Design Principles
- Separation of Concerns: UI, API/controllers, services, data
- Facade Pattern: DataService unifies data access
- Adapter Pattern: lib/ai/tools wrap external calls (GitHubTool, ProjectTool, SkillTool)
- Serverless API Routes in Next.js (scalable, on-demand)
- React Server Components vs Client Components (app/ vs components/ui)

- Clear, consistent labels for each node

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Side
    subgraph "Client Side (Browser)"
        direction TB
        User((User)):::external
        AppPages["App Pages (app/)"]:::frontend
        UIComponents["UI Components (components/)"]:::frontend
        UseChat["useChat Hook"]:::frontend
    end

    %% API Layer
    subgraph "API Layer (Next.js API Routes)"
        direction TB
        ChatRoute["/api/chat"]:::api
        ProjectsRoute["/api/projects"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        ChatbotService["ChatbotService"]:::service
        DataService["DataService"]:::service
        GitHubSyncService["GitHubSyncService"]:::service
        ProjectAutomationService["ProjectAutomationService"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        PersonalData[/"personal-data.ts"/]:::data
    end

    %% AI Integration
    subgraph "AI Integration"
        direction TB
        KnowledgeBase["knowledge-base.ts"]:::ai
        MCPSystem["mcp-system.ts"]:::ai
        ToolGithub["github-tool.ts"]:::ai
        ToolProject["project-tool.ts"]:::ai
        ToolSkill["skill-tool.ts"]:::ai
    end

    %% Utility
    Utils["utils.ts"]:::utility

    %% External Systems
    subgraph "External Systems"
        direction TB
        GitHubAPI[(GitHub REST API)]:::external
        OpenAI[(OpenAI API)]:::external
    end

    %% Connections - Client to API
    User -->|"views"| AppPages
    AppPages -->|"renders"| UIComponents
    UIComponents -->|"uses hook"| UseChat
    UseChat -->|"POST /api/chat"| ChatRoute
    UIComponents -->|"fetchProjects()"| ProjectsRoute

    %% API to Service
    ChatRoute -->|"sendMessage()"| ChatbotService
    ProjectsRoute -->|"syncProjects()"| GitHubSyncService
    ProjectsRoute -->|"processProjects()"| ProjectAutomationService
    ProjectsRoute -->|"getCachedData()"| DataService

    %% Service Interactions
    ChatbotService -->|"getData()"| DataService
    GitHubSyncService -->|"cacheData()"| DataService
    ProjectAutomationService -->|"cacheData()"| DataService

    DataService -->|"getStaticData()"| PersonalData

    ChatbotService -->|"query"| KnowledgeBase
    ChatbotService -->|"query"| MCPSystem
    ChatbotService -->|"use"| ToolGithub
    ChatbotService -->|"use"| ToolProject
    ChatbotService -->|"use"| ToolSkill

    ToolGithub -->|"fetch repos"| GitHubAPI
    GitHubSyncService -->|"fetch repos"| GitHubAPI

    ChatbotService -->|"invoke"| OpenAI

    %% Utility to Services
    Utils -.-> ChatbotService
    Utils -.-> DataService
    Utils -.-> GitHubSyncService
    Utils -.-> ProjectAutomationService

    %% Click Events
    click AppPages "https://github.com/erazor48/ethan-portfolio/tree/main/app/"
    click UIComponents "https://github.com/erazor48/ethan-portfolio/tree/main/components/"
    click UseChat "https://github.com/erazor48/ethan-portfolio/blob/main/components/hooks/useChat.ts"
    click ChatRoute "https://github.com/erazor48/ethan-portfolio/blob/main/app/api/chat/route.ts"
    click ProjectsRoute "https://github.com/erazor48/ethan-portfolio/blob/main/app/api/projects/route.ts"
    click ChatbotService "https://github.com/erazor48/ethan-portfolio/blob/main/lib/services/chatbot-service.ts"
    click DataService "https://github.com/erazor48/ethan-portfolio/blob/main/lib/services/data-service.ts"
    click GitHubSyncService "https://github.com/erazor48/ethan-portfolio/blob/main/lib/services/github-sync.ts"
    click ProjectAutomationService "https://github.com/erazor48/ethan-portfolio/blob/main/lib/services/project-automation.ts"
    click PersonalData "https://github.com/erazor48/ethan-portfolio/blob/main/lib/data/personal-data.ts"
    click KnowledgeBase "https://github.com/erazor48/ethan-portfolio/blob/main/lib/ai/knowledge-base.ts"
    click MCPSystem "https://github.com/erazor48/ethan-portfolio/blob/main/lib/ai/mcp-system.ts"
    click ToolGithub "https://github.com/erazor48/ethan-portfolio/blob/main/lib/ai/tools/github-tool.ts"
    click ToolProject "https://github.com/erazor48/ethan-portfolio/blob/main/lib/ai/tools/project-tool.ts"
    click ToolSkill "https://github.com/erazor48/ethan-portfolio/blob/main/lib/ai/tools/skill-tool.ts"
    click Utils "https://github.com/erazor48/ethan-portfolio/blob/main/lib/utils.ts"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef api fill:#90EE90,stroke:#333,stroke-width:1px
    classDef service fill:#FFD700,stroke:#333,stroke-width:1px
    classDef data fill:#FFB6C1,stroke:#333,stroke-width:1px
    classDef ai fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef utility fill:#D8BFD8,stroke:#333,stroke-width:1px
```
