# cristiancastineiras/dotchat architecture

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

- Interactive diagram: https://gitdiagram.com/cristiancastineiras/dotchat
- Repository: https://github.com/cristiancastineiras/dotchat

## Overview

#### Purpose and entry points
dotChat is a self-hosted, terminal-first real-time chat platform. It supports public/private rooms, direct conversations, encrypted messages and attachments, presence, and separate administration.

Primary executables:
- ASP.NET Core server/API and SignalR host: `src/Chat.Servidor/Program.cs`
- Interactive user CLI: `src/Chat.ClienteCli/Program.cs`
- Interactive administration CLI: `src/Chat.AdminCli/Program.cs`
- Containerized deployment and reverse proxy: `docker-compose.yml`, `Dockerfile`, `despliegue/nginx.conf`

#### Layered core and domain boundary
The solution follows Domain → Application → Infrastructure → Server layering. The domain owns chat concepts and repository/unit-of-work contracts, without persistence or transport dependencies.
- Entities: `src/Chat.Dominio/Entidades/Usuario.cs`, `src/Chat.Dominio/Entidades/Sala.cs`, `src/Chat.Dominio/Entidades/Mensaje.cs`
- Persistence contracts: `src/Chat.Dominio/Abstracciones/IRepositorioMensajes.cs`, `src/Chat.Dominio/Abstracciones/IUnidadDeTrabajo.cs`
- Domain failures provide the application/server error boundary: `src/Chat.Dominio/Excepciones/`

#### Application command/query pipeline
The application layer implements lightweight hand-rolled CQRS: endpoints and internal callers dispatch commands/queries to handlers through a central dispatcher. Commands mutate state; queries project DTOs for clients.
- Dispatcher contracts: `src/Chat.Aplicacion/Cqrs/Contratos.cs`, `src/Chat.Aplicacion/Cqrs/Despachador.cs`
- Core mutations: `src/Chat.Aplicacion/Comandos/Mensajes/ComandoEnviarMensaje.cs`, `src/Chat.Aplicacion/Comandos/Salas/ComandoCrearSala.cs`
- Reads and DTO boundary: `src/Chat.Aplicacion/Consultas/Mensajes/ConsultaObtenerMensajes.cs`, `src/Chat.Aplicacion/Dtos/DtosMensaje.cs`

#### HTTP API, authentication, and realtime delivery
The server exposes grouped endpoint modules for authentication, users, rooms, messages, attachments, diagnostics, and administration. Global exception handling turns domain/application failures into transport responses. SignalR is the realtime boundary for messages, typing, and connection activity.
- API composition and middleware: `src/Chat.Servidor/Program.cs`, `src/Chat.Servidor/Configuracion/ManejadorExcepcionesGlobal.cs`
- Transport modules: `src/Chat.Servidor/Endpoints/EndpointsMensajes.cs`, `src/Chat.Servidor/Endpoints/EndpointsSalas.cs`
- Hub and application notification adapter: `src/Chat.Servidor/Hubs/ChatHub.cs`, `src/Chat.Servidor/Servicios/NotificadorSignalR.cs`
- JWT/session abstractions and implementation: `src/Chat.Aplicacion/Servicios/EmisorSesiones.cs`, `src/Chat.Infraestructura/Seguridad/GeneradorTokensJwt.cs`

#### Persistence, encrypted content, and object storage
PostgreSQL is the system of record through EF Core. Repositories implement domain contracts and commit through a unit of work. Message encryption occurs before stored content reaches persistence; attachments are processed then encrypted and stored separately in S3-compatible MinIO.
- EF context/repositories: `src/Chat.Infraestructura/Persistencia/ContextoChat.cs`, `src/Chat.Infraestructura/Persistencia/Repositorios/RepositorioMensajes.cs`
- Encryption: `src/Chat.Infraestructura/Seguridad/ServicioCifradorMensajes.cs`, `src/Chat.Infraestructura/Seguridad/FlujoCifrador.cs`
- Attachment pipeline: `src/Chat.Aplicacion/Comandos/Mensajes/ComandoSubirAdjunto.cs`, `src/Chat.Infraestructura/Almacenamiento/AlmacenObjetosS3.cs`

#### Distributed runtime services
Docker Compose runs server replicas behind nginx, plus PostgreSQL, Valkey, MinIO, Jaeger, and Seq. Valkey supports cache, distributed presence/connection registration, rate limits, and replica coordination; in-memory alternatives exist for local/single-instance behavior.
- Cache and Valkey setup: `src/Chat.Infraestructura/Cache/ServicioCacheFusion.cs`, `src/Chat.Infraestructura/ExtensionesValkey.cs`
- Presence and replica coordination: `src/Chat.Infraestructura/Presencia/RegistroConexionesValkey.cs`, `src/Chat.Servidor/Servicios/ServicioLatidoReplica.cs`
- Telemetry and health wiring: `src/Chat.Servidor/Configuracion/ExtensionesTelemetria.cs`, `src/Chat.Servidor/Configuracion/ExtensionesSalud.cs`

#### Terminal clients and operational control
The user CLI owns local session state, calls the REST API, and subscribes to SignalR to render interactive conversations and inline images. The admin CLI calls administration endpoints for user, room, cache, message, and diagnostics operations.
- User client orchestration: `src/Chat.ClienteCli/Servicios/AplicacionChat.cs`, `src/Chat.ClienteCli/Servicios/ClienteTiempoReal.cs`
- Session/API boundary: `src/Chat.ClienteCli/Servicios/AlmacenSesion.cs`, `src/Chat.ClienteCli/Servicios/ClienteApi.cs`
- Admin API client and command shell: `src/Chat.AdminCli/Servicios/ClienteAdminApi.cs`, `src/Chat.AdminCli/Infraestructura/ConsolaAdminInteractiva.cs`

Main entry points: [`src/Chat.Aplicacion/Comandos/Mensajes/ComandoEnviarMensaje.cs`](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Aplicacion/Comandos/Mensajes/ComandoEnviarMensaje.cs) (Message workflows), [`src/Chat.Servidor/Program.cs`](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Program.cs) (Server host), [`src/Chat.Servidor/Endpoints/EndpointsMensajes.cs`](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Endpoints/EndpointsMensajes.cs) (Endpoint modules), [`docker-compose.yml`](https://github.com/cristiancastineiras/dotchat/blob/main/docker-compose.yml) (Compose & nginx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Terminal clients"]
  node_user_cli["User CLI<br/>interactive client<br/>[AplicacionChat.cs]"]
  node_user_api_session["API client &amp; session<br/>client boundary<br/>[ClienteApi.cs]"]
  node_user_realtime["Realtime client<br/>SignalR client"]
  node_admin_cli["Admin CLI<br/>interactive client"]
  node_admin_api_client["Admin API client<br/>HTTP client<br/>[ClienteAdminApi.cs]"]
end

subgraph group_server["Server transport"]
  node_server_host["Server host<br/>ASP.NET Core host<br/>[Program.cs]"]
  node_endpoint_modules["Endpoint modules<br/>HTTP API"]
  node_exception_boundary["Exception boundary<br/>middleware"]
  node_signalr_hub["Chat hub<br/>SignalR hub<br/>[ChatHub.cs]"]
  node_realtime_notifier["SignalR notifier<br/>notification adapter"]
end

subgraph group_core["Core layers"]
  node_cqrs_dispatcher{{"CQRS dispatcher<br/>application pipeline<br/>[Despachador.cs]"}}
  node_message_workflows["Message workflows<br/>commands &amp; queries"]
  node_domain{{"Chat domain<br/>entities &amp; contracts<br/>[Mensaje.cs]"}}
  node_auth_sessions["JWT sessions<br/>security service"]
  node_persistence["EF repositories<br/>persistence adapter"]
  node_encryption["Content encryption<br/>security adapter"]
end

subgraph group_runtime["Distributed runtime"]
  node_postgres[("PostgreSQL<br/>system of record<br/>[docker-compose.yml]")]
  node_object_storage[("MinIO<br/>S3 object storage")]
  node_valkey[("Valkey<br/>distributed state")]
  node_deployment["Compose &amp; nginx<br/>deployment topology<br/>[docker-compose.yml]"]
end

node_user_cli -->|"uses"| node_user_api_session
node_user_cli -->|"subscribes"| node_user_realtime
node_admin_cli -->|"uses"| node_admin_api_client
node_user_api_session -->|"REST"| node_endpoint_modules
node_admin_api_client -->|"admin REST"| node_endpoint_modules
node_user_realtime -->|"SignalR"| node_signalr_hub
node_deployment -->|"routes to replicas"| node_server_host
node_deployment -->|"runs"| node_postgres
node_deployment -->|"runs"| node_valkey
node_deployment -->|"runs"| node_object_storage
node_server_host -->|"maps"| node_endpoint_modules
node_server_host -->|"uses"| node_exception_boundary
node_server_host -->|"hosts"| node_signalr_hub
node_endpoint_modules -->|"dispatches"| node_cqrs_dispatcher
node_signalr_hub -->|"dispatches"| node_cqrs_dispatcher
node_endpoint_modules -->|"authenticates"| node_auth_sessions
node_cqrs_dispatcher -->|"invokes"| node_message_workflows
node_message_workflows -->|"applies rules"| node_domain
node_message_workflows -->|"reads and writes"| node_persistence
node_message_workflows -->|"encrypts"| node_encryption
node_message_workflows -->|"stores attachments"| node_object_storage
node_message_workflows -->|"notifies"| node_realtime_notifier
node_persistence -.->|"implements contracts"| node_domain
node_persistence -->|"EF Core"| node_postgres
node_realtime_notifier -->|"publishes"| node_signalr_hub
node_server_host -->|"presence and coordination"| node_valkey

click node_user_cli "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.ClienteCli/Servicios/AplicacionChat.cs"
click node_user_api_session "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.ClienteCli/Servicios/ClienteApi.cs"
click node_user_realtime "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.ClienteCli/Servicios/ClienteTiempoReal.cs"
click node_admin_cli "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.AdminCli/Infraestructura/ConsolaAdminInteractiva.cs"
click node_admin_api_client "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.AdminCli/Servicios/ClienteAdminApi.cs"
click node_server_host "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Program.cs"
click node_endpoint_modules "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Endpoints/EndpointsMensajes.cs"
click node_exception_boundary "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Configuracion/ManejadorExcepcionesGlobal.cs"
click node_signalr_hub "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Hubs/ChatHub.cs"
click node_cqrs_dispatcher "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Aplicacion/Cqrs/Despachador.cs"
click node_message_workflows "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Aplicacion/Comandos/Mensajes/ComandoEnviarMensaje.cs"
click node_domain "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Dominio/Entidades/Mensaje.cs"
click node_auth_sessions "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Seguridad/GeneradorTokensJwt.cs"
click node_persistence "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Persistencia/Repositorios/RepositorioMensajes.cs"
click node_encryption "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Seguridad/ServicioCifradorMensajes.cs"
click node_postgres "https://github.com/cristiancastineiras/dotchat/blob/main/docker-compose.yml"
click node_object_storage "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Almacenamiento/AlmacenObjetosS3.cs"
click node_valkey "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/ExtensionesValkey.cs"
click node_realtime_notifier "https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Servicios/NotificadorSignalR.cs"
click node_deployment "https://github.com/cristiancastineiras/dotchat/blob/main/docker-compose.yml"

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_user_cli,node_user_api_session,node_user_realtime,node_admin_cli,node_admin_api_client toneBlue
class node_server_host,node_endpoint_modules,node_exception_boundary,node_signalr_hub,node_realtime_notifier toneAmber
class node_cqrs_dispatcher,node_message_workflows,node_domain,node_auth_sessions,node_persistence,node_encryption toneMint
class node_postgres,node_object_storage,node_valkey,node_deployment toneRose
```

## Components

### Terminal clients

- [User CLI](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.ClienteCli/Servicios/AplicacionChat.cs): interactive client · Interactive chat and conversation renderer. · `src/Chat.ClienteCli/Servicios/AplicacionChat.cs`
- [API client & session](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.ClienteCli/Servicios/ClienteApi.cs): client boundary · Persists sessions and calls REST endpoints. · `src/Chat.ClienteCli/Servicios/ClienteApi.cs`
- [Realtime client](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.ClienteCli/Servicios/ClienteTiempoReal.cs): SignalR client · `src/Chat.ClienteCli/Servicios/ClienteTiempoReal.cs`
- [Admin CLI](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.AdminCli/Infraestructura/ConsolaAdminInteractiva.cs): interactive client · Administrative command shell. · `src/Chat.AdminCli/Infraestructura/ConsolaAdminInteractiva.cs`
- [Admin API client](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.AdminCli/Servicios/ClienteAdminApi.cs): HTTP client · `src/Chat.AdminCli/Servicios/ClienteAdminApi.cs`

### Server transport

- [Server host](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Program.cs): ASP.NET Core host · Composes API, middleware, DI, and runtime services. · `src/Chat.Servidor/Program.cs`
- [Endpoint modules](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Endpoints/EndpointsMensajes.cs): HTTP API · Auth, user, room, message, attachment, and admin endpoints. · `src/Chat.Servidor/Endpoints/EndpointsMensajes.cs`
- [Exception boundary](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Configuracion/ManejadorExcepcionesGlobal.cs): middleware · Maps domain and application failures to transport responses. · `src/Chat.Servidor/Configuracion/ManejadorExcepcionesGlobal.cs`
- [Chat hub](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Hubs/ChatHub.cs): SignalR hub · Realtime messages, typing, and connection activity. · `src/Chat.Servidor/Hubs/ChatHub.cs`
- [SignalR notifier](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Servidor/Servicios/NotificadorSignalR.cs): notification adapter · Publishes application notifications to hub clients. · `src/Chat.Servidor/Servicios/NotificadorSignalR.cs`

### Core layers

- [CQRS dispatcher](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Aplicacion/Cqrs/Despachador.cs): application pipeline · Dispatches commands and queries to handlers. · `src/Chat.Aplicacion/Cqrs/Despachador.cs`
- [Message workflows](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Aplicacion/Comandos/Mensajes/ComandoEnviarMensaje.cs): commands & queries · Send, retrieve, and upload attachment workflows. · `src/Chat.Aplicacion/Comandos/Mensajes/ComandoEnviarMensaje.cs`
- [Chat domain](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Dominio/Entidades/Mensaje.cs): entities & contracts · Users, rooms, messages, repositories, unit of work, and failures. · `src/Chat.Dominio/Entidades/Mensaje.cs`
- [JWT sessions](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Seguridad/GeneradorTokensJwt.cs): security service · Issues and validates session tokens. · `src/Chat.Infraestructura/Seguridad/GeneradorTokensJwt.cs`
- [EF repositories](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Persistencia/Repositorios/RepositorioMensajes.cs): persistence adapter · Implements domain repositories and unit-of-work commits. · `src/Chat.Infraestructura/Persistencia/Repositorios/RepositorioMensajes.cs`
- [Content encryption](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Seguridad/ServicioCifradorMensajes.cs): security adapter · Encrypts message and attachment content before storage. · `src/Chat.Infraestructura/Seguridad/ServicioCifradorMensajes.cs`

### Distributed runtime

- [PostgreSQL](https://github.com/cristiancastineiras/dotchat/blob/main/docker-compose.yml): system of record · `docker-compose.yml`
- [MinIO](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/Almacenamiento/AlmacenObjetosS3.cs): S3 object storage · Stores encrypted attachments. · `src/Chat.Infraestructura/Almacenamiento/AlmacenObjetosS3.cs`
- [Valkey](https://github.com/cristiancastineiras/dotchat/blob/main/src/Chat.Infraestructura/ExtensionesValkey.cs): distributed state · Cache, presence, rate limits, and replica coordination. · `src/Chat.Infraestructura/ExtensionesValkey.cs`
- [Compose & nginx](https://github.com/cristiancastineiras/dotchat/blob/main/docker-compose.yml): deployment topology · Routes traffic to replicated server containers and backing services. · `docker-compose.yml`

## Connections

- User CLI → API client & session: uses
- User CLI → Realtime client: subscribes
- Admin CLI → Admin API client: uses
- API client & session → Endpoint modules: REST
- Admin API client → Endpoint modules: admin REST
- Realtime client → Chat hub: SignalR
- Compose & nginx → Server host: routes to replicas
- Compose & nginx → PostgreSQL: runs
- Compose & nginx → Valkey: runs
- Compose & nginx → MinIO: runs
- Server host → Endpoint modules: maps
- Server host → Exception boundary: uses
- Server host → Chat hub: hosts
- Endpoint modules → CQRS dispatcher: dispatches
- Chat hub → CQRS dispatcher: dispatches
- Endpoint modules → JWT sessions: authenticates
- CQRS dispatcher → Message workflows: invokes
- Message workflows → Chat domain: applies rules
- Message workflows → EF repositories: reads and writes
- Message workflows → Content encryption: encrypts
- Message workflows → MinIO: stores attachments
- Message workflows → SignalR notifier: notifies
- EF repositories → Chat domain: implements contracts
- EF repositories → PostgreSQL: EF Core
- SignalR notifier → Chat hub: publishes
- Server host → Valkey: presence and coordination