# cleanengine/cleanengine-fe architecture

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

- Interactive diagram: https://gitdiagram.com/cleanengine/cleanengine-fe
- Repository: https://github.com/cleanengine/cleanengine-fe

## Overview

##### Project Type and Purpose
- Invest Future is a **front-end web application** built with React that combines **SSR/SSG** (for landing pages, SEO) and a **SPA trade page**, consuming real-time market data and exposing mock-investment functionality.
- Core features: real-time charts (AmCharts), order entry, chat, and simulated buy/sell bots that interpolate between user actions and live market data via Stomp.js.

##### File Structure
- Top-level configs: `Dockerfile`, `vite.config.ts`, GitHub Actions workflows, Sonar, Husky hooks → indicates containerized build & CI pipeline.
- `src/app/entry.server.tsx` & `entry.client.tsx` + `react-router.config.ts` → SSR server & client hydration using React Router v7 in “framework mode.”
- FSD pattern: `src/entities`, `src/features`, `src/shared`, `src/widgets` → high-cohesion, feature-based modules.
- Real-time / API layers:
- REST API clients under `src/entities/*/api/*.endpoint.ts` and `src/features/*/api/*`
- WebSocket (Stomp) provider under `src/app/provider/StompProvider.tsx`
- Mocking layer: `src/mocks` (MSW handlers) for dev/testing.
- State machines: XState models under features like `chat/model/chat.machine.ts`, `order/models/form.machine.ts`.

##### Extract Key Architectural Insights from README
- **Event-Driven Modeling**: UI state is managed by XState machines.
- **Feature Sliced Design**: Modules grouped by domain (entities, features, shared, widgets).
- **Hybrid Rendering**: SSR/SSG + SPA for `/trade`.
- **Real-Time Communication**: AmCharts + Stomp.js.
- **Bots**: Backend bots reconcile divergence between simulated and live data.

##### Main Components
A. **Client Browser**
- Initial load → SSR HTML
- Hydration → React Router switch
- Trade page → full SPA for dynamic charts & order entry
- Other pages → SSR/SSG served content
B. **Front-end Application**
- **Server Node** (instrument.server.mjs + Vite SSR plugin)
- **Client Bundle** (Vite build output served as static assets)
C. **API Layer**
- **REST Endpoints**: `/coin`, `/order`, `/session`, `/user`, `/chat`
- **Auth Service**: Kakao Login API
D. **WebSocket (Stomp) Server**
- Streams real-time market data → order book, trades
E. **Market-Simulation Bots** (external microservice or part of API)
- Interpolates divergence by auto-trading on real market
F. **3rd-Party Services**
- Real Market Data Provider
- Kakao OAuth
G. **Dev/Test Tooling**
- MSW mocks (browser & node)
- CI/CD (GitHub Actions)
- Docker containerization

##### Relationships & Data Flows
1. **Browser** requests page → **SSR Server** renders HTML via `entry.server.tsx`.
2. HTML + JS → Browser hydrates client bundle (`entry.client.tsx`).
3. For `/trade` route: SPA kicks in, subscribes to **Stomp WebSocket** for live ticks & order book.
4. **User Actions** (order submission, chat messages) → REST POST to **API Server**.
5. API Server triggers backend **bots** if chart divergence > threshold → places real trades via Market Data Provider.
6. Market Data Provider & API Server push updates via WebSocket → front-end XState machines update UI.
7. Auth flows via Kakao → OAuth redirects → session endpoint → user context provider.

##### Architectural Patterns & Principles
- **Event-Driven State Machines** (XState) for robust UI flows.
- **Feature-Sliced Design** for modular, high-cohesion code.
- **Hybrid SSR/SPA** leveraging React Router framework mode.
- **Facade Layers**: `httpClient.tsx` abstracts REST calls, `StompProvider` abstracts WS.
- **Mock-First**: MSW intercepts API calls in dev/test.

##### Don’t Overthink—Be Detailed
- Folder/module to a component if it has its own runtime role (e.g., XState machine → “Event-Driven State Layer”).
- SSR server, client router, REST facade, WebSocket connector, charting library, state machines, API server, bots, external providers.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Front-End Components
    subgraph "Front-End Application"
        direction TB
        Browser["Client Browser"]:::frontend
        SSRServer["SSR Server\n(instrument.server.mjs)"]:::frontend
        EntryServer["entry.server.tsx"]:::frontend
        EntryClient["entry.client.tsx"]:::frontend
        Router["React Router\n(react-router.config.ts)"]:::frontend
        StompProv["StompProvider\n(src/app/provider/StompProvider.tsx)"]:::frontend
        HttpClient["HTTP Client Facade\n(src/shared/api/httpClient.tsx)"]:::frontend
        XState["XState State Layer"]:::frontend
        Chart["Real-Time Chart Components\n(src/features/tradeview/ui/StockChart/*)"]:::frontend
        OrderBook["Order Book UI\n(src/features/tradeview/ui/Orderbook/index.tsx)"]:::frontend
    end

    %% API & Real-Time Layers
    subgraph "API & Real-Time Services"
        direction TB
        APIServer["REST API Server"]:::backend
        CoinAPI["Coin Endpoint\n(src/entities/coin/api/coin.endpoint.ts)"]:::backend
        SessionAPI["Session Endpoint\n(src/entities/session/api/session.endpoint.ts)"]:::backend
        UserAPI["User Endpoint\n(src/entities/user/api/user.endpoint.ts)"]:::backend
        AuthAPI["Auth Endpoint\n(src/features/auth/api/auth.endpoints.ts)"]:::backend
        ChatAPI["Chat Endpoint\n(src/features/chat/api/chat.endpoint.ts)"]:::backend
        OrderAPI["Order Endpoint\n(src/features/order/api/order.endpoint.ts)"]:::backend
        TradeviewAPI["Tradeview Endpoint\n(src/features/tradeview/api/tradeview.endpoints.ts)"]:::backend
        WS["WebSocket (Stomp) Server"]:::backend
        Bots["Market-Simulation Bots"]:::backend
        MarketData["Real Market Data Provider"]:::external
        Kakao["Kakao OAuth Service"]:::external
    end

    %% Mock & Dev/Test
    subgraph "Dev/Test Tooling"
        direction TB
        MSWHandlers["MSW Handlers\n(src/mocks/handlers.ts)"]:::mock
        MSWBrowser["MSW Browser\n(src/mocks/browser.ts)"]:::mock
        MSWServer["MSW Server\n(src/mocks/server.ts)"]:::mock
        Docker["Dockerfile"]:::backend
        CI["CI/CD Workflows\n(.github/workflows/*.yml)"]:::backend
        ViteConf["Vite Config\n(vite.config.ts)"]:::backend
        TestSetup["Test Setup\n(setupTests.ts)"]:::backend
    end

    %% Browser to SSR & Client Bundle
    Browser -->|"HTTP GET\n(html)"| SSRServer
    SSRServer --> EntryServer
    EntryServer --> Router
    EntryServer --> EntryClient
    EntryClient --> Router
    Router -->|"SPA /trade"| StompProv
    Router -->|"SSG/SSR other routes"| HttpClient

    %% State Layer and UI Components
    StompProv -->|"WebSocket WSS"| WS
    HttpClient -->|"REST HTTPS"| APIServer
    StompProv --> XState
    HttpClient --> XState
    XState --> Chart
    XState --> OrderBook

    %% API Server internals
    APIServer --> CoinAPI
    APIServer --> SessionAPI
    APIServer --> UserAPI
    APIServer --> AuthAPI
    APIServer --> ChatAPI
    APIServer --> OrderAPI
    APIServer --> TradeviewAPI

    %% Auth and External
    Browser -->|"OAuth Redirect"| Kakao
    Kakao -->|"OAuth Callback"| SessionAPI

    %% Bots and Market Data
    APIServer -->|"Trigger Bots"| Bots
    Bots -->|"Real Trades"| MarketData
    MarketData -->|"Market Ticks"| WS
    MarketData -->|"Market Data"| APIServer

    %% Mocking
    MSWBrowser -.-> Browser
    MSWServer -.-> APIServer
    MSWHandlers -.-> MSWBrowser
    MSWHandlers -.-> MSWServer

    %% Dev/Test & Infra
    Docker --> SSRServer
    Docker --> APIServer
    CI --> Docker
    CI --> ViteConf
    TestSetup --> MSWServer
    TestSetup --> MSWBrowser

    %% Click Events
    click SSRServer "https://github.com/cleanengine/cleanengine-fe/blob/main/instrument.server.mjs"
    click EntryServer "https://github.com/cleanengine/cleanengine-fe/blob/main/src/app/entry.server.tsx"
    click EntryClient "https://github.com/cleanengine/cleanengine-fe/blob/main/src/app/entry.client.tsx"
    click Router "https://github.com/cleanengine/cleanengine-fe/blob/main/react-router.config.ts"
    click StompProv "https://github.com/cleanengine/cleanengine-fe/blob/main/src/app/provider/StompProvider.tsx"
    click HttpClient "https://github.com/cleanengine/cleanengine-fe/blob/main/src/shared/api/httpClient.tsx"
    click CoinAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/entities/coin/api/coin.endpoint.ts"
    click SessionAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/entities/session/api/session.endpoint.ts"
    click UserAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/entities/user/api/user.endpoint.ts"
    click AuthAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/features/auth/api/auth.endpoints.ts"
    click ChatAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/features/chat/api/chat.endpoint.ts"
    click OrderAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/features/order/api/order.endpoint.ts"
    click TradeviewAPI "https://github.com/cleanengine/cleanengine-fe/blob/main/src/features/tradeview/api/tradeview.endpoints.ts"
    click MSWHandlers "https://github.com/cleanengine/cleanengine-fe/blob/main/src/mocks/handlers.ts"
    click MSWBrowser "https://github.com/cleanengine/cleanengine-fe/blob/main/src/mocks/browser.ts"
    click MSWServer "https://github.com/cleanengine/cleanengine-fe/blob/main/src/mocks/server.ts"
    click Docker "https://github.com/cleanengine/cleanengine-fe/tree/main/Dockerfile"
    click CI "https://github.com/cleanengine/cleanengine-fe/tree/main/.github/workflows/"
    click ViteConf "https://github.com/cleanengine/cleanengine-fe/blob/main/vite.config.ts"
    click TestSetup "https://github.com/cleanengine/cleanengine-fe/blob/main/setupTests.ts"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#4D7EA8,color:#000
    classDef backend fill:#D0FFD8,stroke:#4DA84D,color:#000
    classDef external fill:#FFE7B0,stroke:#D9A300,color:#000
    classDef mock stroke-dasharray: 5 5,fill:#F2F2F2,stroke:#999,color:#000
```
