# ranpoe/init-nestjs architecture

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

- Interactive diagram: https://gitdiagram.com/ranpoe/init-nestjs
- Repository: https://github.com/ranpoe/init-nestjs

## Overview

This repository provides a chat UI and NestJS API that proxy prompts to a configured local Ollama instance. The principal workflow is user prompt → frontend session state and API request → chat controller → Ollama service → generated text displayed in the conversation. The backend also exposes health and Prometheus metrics endpoints, and includes trace/session correlation and logging infrastructure. Source excerpts support the chat, health, and metrics relationships; observability deployment wiring is represented only at the directory level because its configuration was not sampled.

Main entry points: [`frontend/src/App.tsx`](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/App.tsx) (Chat screen), [`frontend/src/hooks/useChat.ts`](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/hooks/useChat.ts) (Conversation state), [`src/ollama/ollama.controller.ts`](https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/ollama.controller.ts) (Chat endpoint), [`src/main.ts`](https://github.com/ranpoe/init-nestjs/blob/main/src/main.ts) (NestJS bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Chat frontend"]
  node_app["Chat screen<br/>[App.tsx]"]
  node_chat_state["Conversation state<br/>[useChat.ts]"]
  node_chat_api["Chat API client<br/>[chat.ts]"]
  node_chat_view["Message list"]
  node_chat_input["Prompt input<br/>[ChatInput.tsx]"]
  node_session_badge["Session badge<br/>[CopyIdBadge.tsx]"]
end

subgraph group_backend["Chat API"]
  node_api_runtime["NestJS bootstrap<br/>[main.ts]"]
  node_app_module["Application wiring<br/>[app.module.ts]"]
  node_chat_controller["Chat endpoint"]
  node_ollama_service["Generation proxy<br/>[ollama.service.ts]"]
  node_env_config["Environment validation<br/>[env.validation.ts]"]
end

subgraph group_operations["Operations"]
  node_health["Health probes"]
  node_metrics_interceptor["Request metrics"]
  node_metrics_service[("Metrics registry<br/>[metrics.service.ts]")]
  node_metrics_endpoint["Metrics endpoint"]
end

subgraph group_telemetry["Telemetry"]
  node_chat_session["Session tagging"]
  node_trace_setup["Trace setup<br/>[tracing.ts]"]
  node_obs_stack["Observability stack"]
end

node_user(("Chat user"))
node_ollama{{"Ollama"}}
node_prometheus{{"Prometheus"}}

node_user -->|"uses"| node_app
node_app -->|"uses"| node_chat_state
node_app -->|"renders"| node_chat_view
node_app -->|"renders"| node_chat_input
node_app -->|"renders"| node_session_badge
node_chat_input -->|"submits prompt"| node_chat_state
node_chat_state -->|"sends request"| node_chat_api
node_chat_state -->|"provides messages"| node_chat_view
node_chat_state -->|"provides session ID"| node_session_badge
node_chat_api -.->|"posts chat"| node_chat_controller
node_api_runtime -->|"starts"| node_app_module
node_app_module -->|"validates configuration"| node_env_config
node_chat_controller -->|"generates text"| node_ollama_service
node_chat_controller -->|"applies interceptor"| node_chat_session
node_ollama_service -->|"requests generation"| node_ollama
node_health -->|"pings readiness"| node_ollama
node_metrics_interceptor -->|"records requests"| node_metrics_service
node_metrics_endpoint -->|"exports metrics"| node_metrics_service
node_prometheus -.->|"scrapes"| node_metrics_endpoint
node_api_runtime -->|"loads tracing"| node_trace_setup
node_trace_setup -.->|"exports telemetry"| node_obs_stack

click node_app "https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/App.tsx"
click node_chat_state "https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/hooks/useChat.ts"
click node_chat_api "https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/api/chat.ts"
click node_chat_view "https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/components/ChatMessageList.tsx"
click node_chat_input "https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/components/ChatInput.tsx"
click node_session_badge "https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/components/CopyIdBadge.tsx"
click node_api_runtime "https://github.com/ranpoe/init-nestjs/blob/main/src/main.ts"
click node_app_module "https://github.com/ranpoe/init-nestjs/blob/main/src/app.module.ts"
click node_chat_controller "https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/ollama.controller.ts"
click node_chat_session "https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/interceptors/chat-session.interceptor.ts"
click node_ollama_service "https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/ollama.service.ts"
click node_health "https://github.com/ranpoe/init-nestjs/blob/main/src/health/health.controller.ts"
click node_metrics_interceptor "https://github.com/ranpoe/init-nestjs/blob/main/src/common/interceptors/metrics.interceptor.ts"
click node_metrics_service "https://github.com/ranpoe/init-nestjs/blob/main/src/common/metrics/metrics.service.ts"
click node_metrics_endpoint "https://github.com/ranpoe/init-nestjs/blob/main/src/common/metrics/metrics.controller.ts"
click node_env_config "https://github.com/ranpoe/init-nestjs/blob/main/src/config/env.validation.ts"
click node_trace_setup "https://github.com/ranpoe/init-nestjs/blob/main/src/tracing.ts"
click node_obs_stack "https://github.com/ranpoe/init-nestjs/tree/main/observability"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app,node_chat_state,node_chat_api,node_chat_view,node_chat_input,node_session_badge,node_user toneBlue
class node_api_runtime,node_app_module,node_chat_controller,node_ollama_service,node_env_config toneAmber
class node_health,node_metrics_interceptor,node_metrics_service,node_metrics_endpoint toneMint
class node_chat_session,node_trace_setup,node_obs_stack toneRose
class node_ollama,node_prometheus toneIndigo
```

## Components

### Chat frontend

- [Chat screen](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Conversation state](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/hooks/useChat.ts): `frontend/src/hooks/useChat.ts`
- [Chat API client](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/api/chat.ts): `frontend/src/api/chat.ts`
- [Message list](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/components/ChatMessageList.tsx): `frontend/src/components/ChatMessageList.tsx`
- [Prompt input](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/components/ChatInput.tsx): `frontend/src/components/ChatInput.tsx`
- [Session badge](https://github.com/ranpoe/init-nestjs/blob/main/frontend/src/components/CopyIdBadge.tsx): `frontend/src/components/CopyIdBadge.tsx`

### Chat API

- [NestJS bootstrap](https://github.com/ranpoe/init-nestjs/blob/main/src/main.ts): `src/main.ts`
- [Application wiring](https://github.com/ranpoe/init-nestjs/blob/main/src/app.module.ts): `src/app.module.ts`
- [Chat endpoint](https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/ollama.controller.ts): `src/ollama/ollama.controller.ts`
- [Generation proxy](https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/ollama.service.ts): `src/ollama/ollama.service.ts`
- [Environment validation](https://github.com/ranpoe/init-nestjs/blob/main/src/config/env.validation.ts): `src/config/env.validation.ts`

### Operations

- [Health probes](https://github.com/ranpoe/init-nestjs/blob/main/src/health/health.controller.ts): `src/health/health.controller.ts`
- [Request metrics](https://github.com/ranpoe/init-nestjs/blob/main/src/common/interceptors/metrics.interceptor.ts): `src/common/interceptors/metrics.interceptor.ts`
- [Metrics registry](https://github.com/ranpoe/init-nestjs/blob/main/src/common/metrics/metrics.service.ts): `src/common/metrics/metrics.service.ts`
- [Metrics endpoint](https://github.com/ranpoe/init-nestjs/blob/main/src/common/metrics/metrics.controller.ts): `src/common/metrics/metrics.controller.ts`

### Telemetry

- [Session tagging](https://github.com/ranpoe/init-nestjs/blob/main/src/ollama/interceptors/chat-session.interceptor.ts): `src/ollama/interceptors/chat-session.interceptor.ts`
- [Trace setup](https://github.com/ranpoe/init-nestjs/blob/main/src/tracing.ts): `src/tracing.ts`
- [Observability stack](https://github.com/ranpoe/init-nestjs/tree/main/observability): `observability`

### Other components

- **Chat user**
- **Ollama**
- **Prometheus**

## Connections

- Chat user → Chat screen: uses (evidence: `frontend/src/App.tsx`)
- Chat screen → Conversation state: uses (evidence: `frontend/src/App.tsx`)
- Chat screen → Message list: renders (evidence: `frontend/src/App.tsx`)
- Chat screen → Prompt input: renders (evidence: `frontend/src/App.tsx`)
- Chat screen → Session badge: renders (evidence: `frontend/src/App.tsx`)
- Prompt input → Conversation state: submits prompt (evidence: `frontend/src/App.tsx`)
- Conversation state → Chat API client: sends request (evidence: `frontend/src/hooks/useChat.ts`)
- Conversation state → Message list: provides messages (evidence: `frontend/src/components/ChatMessageList.tsx`)
- Conversation state → Session badge: provides session ID (evidence: `frontend/src/App.tsx`)
- Chat API client → Chat endpoint: posts chat
- NestJS bootstrap → Application wiring: starts (evidence: `src/main.ts`)
- Application wiring → Environment validation: validates configuration (evidence: `src/app.module.ts`)
- Chat endpoint → Generation proxy: generates text (evidence: `src/ollama/ollama.controller.ts`)
- Chat endpoint → Session tagging: applies interceptor (evidence: `src/ollama/ollama.controller.ts`)
- Generation proxy → Ollama: requests generation (evidence: `src/ollama/ollama.service.ts`)
- Health probes → Ollama: pings readiness (evidence: `src/health/health.controller.ts`)
- Request metrics → Metrics registry: records requests (evidence: `src/common/interceptors/metrics.interceptor.ts`)
- Metrics endpoint → Metrics registry: exports metrics (evidence: `src/common/metrics/metrics.controller.ts`)
- Prometheus → Metrics endpoint: scrapes
- NestJS bootstrap → Trace setup: loads tracing (evidence: `src/main.ts`)
- Trace setup → Observability stack: exports telemetry