# umecchi1098/azurechat architecture

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

- Interactive diagram: https://gitdiagram.com/umecchi1098/azurechat
- Repository: https://github.com/umecchi1098/azurechat

## Overview

##### Main components
- Frontend/UI Layer:
– Found within the src/app and src/features directories, this houses UI pages such as chat, reporting, extensions, persona, and prompt interfaces.
– Contains Next.js components (React components, layout pages, designated loading and error handling screens).

- Backend/API Layer within the same Next.js application (utilizing Next.js API routes):
– In the src/app/(authenticated)/api folder where endpoints for authentication (using NextAuth), chat, document, and images are provided.

- Domain Services & Business Logic:
– Located in src/features across areas like chat services, extension services, authentication helpers, and reporting services.
– This is where the core logic sits (for example, chat API integrations such as OpenAI streaming, Azure AI Search, and other utility functions).

- Infrastructure/Deployment:
– The infra folder holds Azure resource definitions (Bicep, JSON templates, parameters) that provision required Azure services (e.g., Cosmos DB, Key Vault, App Service, etc.).
– The README outlines deployment paths including using the Azure Developer CLI and GitHub actions.

- Configuration & Environment:
– Files like .env.example, tailwind.config, and various config files in src (e.g., next.config.js, tsconfig.json) support both development and production environments.

- Development & CI/CD Pipeline:
– GitHub workflows in the .github/workflows directory indicate automation for validation and CI/CD deployments (e.g., azure-dev-validate.yml, open-ai-app.yml).

##### Relationships and interactions
- The UI layer (chat, persona, extensions pages, etc.) calls the backend API endpoints using Next.js’s API routing.
- API endpoints interact with domain services that integrate with external APIs (Azure Open AI, Azure AI Search, possibly other Azure services via SDKs).
- The infrastructure scripts deploy necessary Azure services, which will be interacted with at runtime (for storage, identity, etc.).
- Authentication and authorization flow through the dedicated Authentication API endpoints (leveraging next-auth implementations and identity provider configuration as outlined in the README).

##### Architectural patterns and design principles
- Layered Architecture:
– A clear separation between the presentation (UI), application (API and domain services), and infrastructure (Azure deployment artifacts).
- Modular and Component-Based Design:
– The usage of Next.js’s file-based routing with its evolving folder structure (e.g., the (authenticated) grouping) supports modular development.
– Domain-specific folders in src/features emphasize separation of concerns (chat, extension, persona, etc.).
- Infrastructure as Code (IaC):
– Using Bicep and JSON files to define and deploy Azure resources programmatically.
- CI/CD Integration:
– GitHub Actions workflows to assist in testing, validating, and deploying the codebase.

- Frontend/UI (Next.js pages and components)
- Backend/API (including authentication, chat, document, and image processing endpoints)
- Domain Logic/Services (chat service integrations, reporting, extensions, etc.)

- User interactions from the client’s browser to the Frontend.
- API calls from the UI to the backend endpoints.
- Communication between backend APIs and domain services (e.g., calls to Azure Open AI or Azure AI Search).
- Deployment and provisioning relationships between the deployed app and Azure Infrastructure components.

- API/Business Logic (green or rounded rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    U["User Browser"]:::external

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        F1["Next.js Pages (src/app)"]:::frontend
        F2["UI Components (src/features)"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        B1["Authentication API (src/app/(authenticated)/api/auth)"]:::backend
        B2["Chat API (src/app/(authenticated)/api/chat/route.ts)"]:::backend
        B3["Document API (src/app/(authenticated)/api/document/route.ts)"]:::backend
        B4["Images API (src/app/(authenticated)/api/images/route.ts)"]:::backend
    end

    %% Domain Services & Business Logic
    subgraph "Domain Services & Business Logic"
        D1["Chat Services (src/features/chat-page/chat-services)"]:::domain
        D2["Authentication Helpers (src/features/auth-page)"]:::domain
        D3["Reporting Services (src/features/reporting-page/reporting-services)"]:::domain
        D4["Extension Services (src/features/extensions-page/extension-services)"]:::domain
        D5["Common Services (src/features/common/services)"]:::domain
    end

    %% Azure Infrastructure
    subgraph "Azure Infrastructure"
        I1["Deployment Scripts (infra)"]:::infra
        I2["Azure Deployment Config (azure.yaml)"]:::infra
        I3["Azure Resources (App Service, Cosmos DB, Key Vault, etc.)"]:::infra
    end

    %% Configuration & Environment
    subgraph "Configuration & Environment"
        C1["Env & Config Files (src/.env.example, next.config.js, tsconfig.json)"]:::config
        C2["Tailwind Configs (src/tailwind.config.js/ts)"]:::config
        C3["ESLint Config (src/.eslintrc.json)"]:::config
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"
        P1["GitHub Workflows (.github/workflows)"]:::cicd
        P2["Dev Container (.devcontainer)"]:::cicd
    end

    %% Connections: User
    U ---|"uses"| F1
    U ---|"uses"| F2

    %% Frontend to Backend API calls
    F1 -->|"apiCall"| B1
    F1 -->|"apiCall"| B2
    F1 -->|"apiCall"| B3
    F1 -->|"apiCall"| B4

    %% Frontend Integration
    F2 -->|"integrates"| F1

    %% Backend APIs to Domain Services
    B1 -->|"logicCall"| D2
    B2 -->|"logicCall"| D1
    B3 -->|"logicCall"| D5
    B4 -->|"logicCall"| D5

    %% Domain Services interconnections
    D1 -->|"uses"| D5

    %% Domain Services call External Azure Resources
    D1 -->|"calls"| I3
    D2 -->|"calls"| I3
    D3 -->|"calls"| I3
    D4 -->|"calls"| I3
    D5 -->|"calls"| I3

    %% CI/CD deploys Infrastructure
    P1 -->|"deploys"| I1
    P1 -->|"deploys"| I2

    %% Configurations used by Frontend and Backend
    C1 --> F1
    C1 --> B1
    C2 --> F1
    C3 --> F1
    C3 --> B1

    %% Azure Infrastructure hosts application runtime
    I3 -->|"hosts"| F1
    I3 -->|"hosts"| B1
    I3 -->|"hosts"| D1

    %% Click Event Mappings
    click F1 "https://github.com/umecchi1098/azurechat/tree/main/src/app"
    click F2 "https://github.com/umecchi1098/azurechat/tree/main/src/features"
    click B1 "https://github.com/umecchi1098/azurechat/tree/main/src/app/(authenticated)/api/auth"
    click B2 "https://github.com/umecchi1098/azurechat/blob/main/src/app/(authenticated)/api/chat/route.ts"
    click B3 "https://github.com/umecchi1098/azurechat/blob/main/src/app/(authenticated)/api/document/route.ts"
    click B4 "https://github.com/umecchi1098/azurechat/blob/main/src/app/(authenticated)/api/images/route.ts"
    click D1 "https://github.com/umecchi1098/azurechat/tree/main/src/features/chat-page/chat-services"
    click D2 "https://github.com/umecchi1098/azurechat/tree/main/src/features/auth-page"
    click D3 "https://github.com/umecchi1098/azurechat/tree/main/src/features/reporting-page/reporting-services"
    click D4 "https://github.com/umecchi1098/azurechat/tree/main/src/features/extensions-page/extension-services"
    click D5 "https://github.com/umecchi1098/azurechat/tree/main/src/features/common/services"
    click I1 "https://github.com/umecchi1098/azurechat/tree/main/infra"
    click I2 "https://github.com/umecchi1098/azurechat/blob/main/azure.yaml"
    click C1 "https://github.com/umecchi1098/azurechat/blob/main/src/.env.example"
    click C2 "https://github.com/umecchi1098/azurechat/blob/main/src/tailwind.config.js"
    click C3 "https://github.com/umecchi1098/azurechat/blob/main/src/.eslintrc.json"
    click P1 "https://github.com/umecchi1098/azurechat/tree/main/.github/workflows"
    click P2 "https://github.com/umecchi1098/azurechat/blob/main/.devcontainer"

    %% Styling Classes
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef domain fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef infra fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef cicd fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef external fill:#fdfd96,stroke:#b5b5b5,stroke-width:2px;
```
