# phanxuanquang/engace architecture

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

- Interactive diagram: https://gitdiagram.com/phanxuanquang/engace
- Repository: https://github.com/phanxuanquang/engace

## Overview

##### Project Type and Purpose
- EngAce is a full-stack application designed to help Vietnamese learners improve their English. It offers multiple interactive features such as an intelligent dictionary, personalized assignments, writing reviews, and an AI-powered chatbot.
- The project leverages a .NET-based backend (found under EngAce.Api) and frontend applications implemented in Next.js/React (as seen in the engace.neo and engace.next directories). It is structured as a monorepo with separated concerns for API services, shared entities, event-driven components, helper libraries, and clearly delineated frontend apps.

##### File Structure
- The backend is housed in the EngAce.Api directory. It follows a standard .NET structure with controllers for various features (Assignment, Chatbot, Dictionary, Healthcheck, Review) and configuration files (appsettings, service dependencies, project files).
- Shared logic and domain models are contained in the Entities directory, while the Events directory encapsulates scopes (for Chat, Healthcheck, Quiz, Review, and Search) indicating an event-based or messaging component in the design.
- Helper functions reside in a dedicated Helper library to support both backend and frontend needs.
- Two frontend directories (engace.neo and engace.next) indicate that the project may have experimented with or supports multiple UI approaches. Both follow Next.js conventions (pages, layouts, components, contexts) and include comprehensive UI components (for chat, assignments, dictionary, writing review, etc.), configuration files, and styling.

- Backend API Server:
- Represented by EngAce.Api, including controllers for each significant feature (intelligent dictionary, assignment generation, writing review, chatbot interactions).
- Configuration management and dependency injections (as seen in appsettings, service dependencies).
- Domain and Event Systems:
- Entities library, representing shared domain models (such as ChatResponse, Comment, Conversation, Quiz, etc.) that underpin the logic in the controllers.
- Optionally, you may note that the Helper library provides additional support to the API.
- Frontend Applications:
- Intelligent Dictionary pages/components.
- Assignment pages (with adaptive learning and quiz generation components).
- Writing review pages designed for detailed feedback.
- Chat interfaces that include controls and message displays.
- That these components orchestrate UI interactions (submission of data, displaying API results) and use common libraries (like context providers, hooks, and UI components).
- External Services and Integration Points:

##### Architectural Patterns and Design Principles
- Separation of concerns: The backend isolated by controllers, domain logic in Entities and Events, and independent frontend apps.
- Incorporate microservices principles if needed by clearly separating each functional domain (dictionary, assignment, writing review, and chatbot) even if they run as part of a single API project.
- Usage of modern frameworks and libraries: .NET for the API, and Next.js/React for the frontends.

##### Instructing the Principal Software Engineer
- Subdivide each major component:
- Under the Backend, include subcomponents for Controllers (Assignment, Chatbot, Dictionary, etc.), Domain Models (Entities), Event Handlers (Events), and Helper utilities.
- Under the Frontend, sketch out the page flow for each feature (chat, assignment, dictionary, writing review) reflecting the file structure in engace.neo and engace.next.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Backend Layer
    subgraph "Backend API"
        EngAce_API("API Server"):::backend
        subgraph "Controllers & Configuration"
            API_Assignment("Assignment Controller"):::backend
            API_Chatbot("Chatbot Controller"):::backend
            API_Dictionary("Dictionary Controller"):::backend
            API_Healthcheck("Healthcheck Controller"):::backend
            API_Review("Review Controller"):::backend
            AppSettings("appsettings.json"):::backend
            ServiceDependencies("serviceDependencies.json"):::backend
        end
    end

    %% Domain and Helper Components
    Entities("Domain Models (Entities)"):::domain
    Events("Event System (Events)"):::events
    Helper_Utilities("Helper Utilities"):::helper

    %% Frontend Layer - Variant EngAce.Neo
    subgraph "Frontend EngAce.Neo"
        Neo_App("engace.neo"):::frontend
        Neo_Dictionary("Dictionary Page"):::frontend
        Neo_Assignment("Assignment Page"):::frontend
        Neo_Review("Writing Review Page"):::frontend
        Neo_Chat("Chat Interface"):::frontend
    end

    %% Frontend Layer - Variant EngAce.Next
    subgraph "Frontend EngAce.Next"
        Next_App("engace.next"):::frontend
        Next_Dictionary("Dictionary Page"):::frontend
        Next_Assignment("Assignment Page"):::frontend
        Next_Review("Writing Review Page"):::frontend
        Next_Chat("Chat Interface"):::frontend
    end

    %% External Services
    External("External AI & GoogleSearch"):::external

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        Backend_Pipeline("Backend Pipeline"):::cicd
        Frontend_Pipeline("Frontend Pipeline"):::cicd
    end

    %% Relationships
    %% Frontend calls Backend API
    Neo_App -->|"calls"| EngAce_API
    Next_App -->|"calls"| EngAce_API

    %% Backend API interactions with shared components
    EngAce_API -->|"uses"| Entities
    EngAce_API -->|"triggers"| Events
    EngAce_API -->|"calls"| Helper_Utilities

    %% Specific integration from Chatbot Controller to External Service
    API_Chatbot -->|"integrates"| External

    %% CI/CD deployment arrows
    Backend_Pipeline -->|"deploys"| EngAce_API
    Frontend_Pipeline -->|"deploys"| Neo_App
    Frontend_Pipeline -->|"deploys"| Next_App

    %% Styles
    classDef backend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef frontend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef domain fill:#FFB6C1,stroke:#000,stroke-width:2px;
    classDef events fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef helper fill:#E6E6FA,stroke:#000,stroke-width:2px;
    classDef external fill:#FFE4B5,stroke:#000,stroke-width:2px;
    classDef cicd fill:#D3D3D3,stroke:#000,stroke-width:2px;

    %% Click Events
    click EngAce_API "https://github.com/phanxuanquang/engace/tree/master/EngAce.Api/"
    click API_Assignment "https://github.com/phanxuanquang/engace/tree/master/EngAce.Api/Controllers/"
    click API_Chatbot "https://github.com/phanxuanquang/engace/tree/master/EngAce.Api/Controllers/"
    click API_Dictionary "https://github.com/phanxuanquang/engace/tree/master/EngAce.Api/Controllers/"
    click API_Healthcheck "https://github.com/phanxuanquang/engace/tree/master/EngAce.Api/Controllers/"
    click API_Review "https://github.com/phanxuanquang/engace/tree/master/EngAce.Api/Controllers/"
    click AppSettings "https://github.com/phanxuanquang/engace/blob/master/EngAce.Api/appsettings.json"
    click ServiceDependencies "https://github.com/phanxuanquang/engace/blob/master/EngAce.Api/Properties/serviceDependencies.json"
    click Entities "https://github.com/phanxuanquang/engace/tree/master/Entities/"
    click Events "https://github.com/phanxuanquang/engace/tree/master/Events/"
    click Helper_Utilities "https://github.com/phanxuanquang/engace/tree/master/Helper/"
    click Neo_App "https://github.com/phanxuanquang/engace/tree/master/engace.neo/"
    click Next_App "https://github.com/phanxuanquang/engace/tree/master/engace.next/"
    click Backend_Pipeline "https://github.com/phanxuanquang/engace/blob/master/.github/workflows/Backend.yml"
    click Frontend_Pipeline "https://github.com/phanxuanquang/engace/blob/master/.github/workflows/Frontend.yml"
```
