# devfullcycle/imersao-ia1 architecture

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

- Interactive diagram: https://gitdiagram.com/devfullcycle/imersao-ia1
- Repository: https://github.com/devfullcycle/imersao-ia1

## Overview

Full Cycle Chat is a team-chat product specified to combine conversations, tasks, notifications, and pluggable AI agents. The intended flow is a person chatting in the web client, asking an agent in a conversation, and receiving its response there; agents may also delegate work or answer business-data questions. The README documents this target architecture, but the checked-in application code is still an early scaffold: the Nest API currently wires configuration, database setup, and error handling, and the agent service is not present in the tree. Connections for the product workflow reflect README documentation, not inspected implementations.

Main entry points: [`docs/hld.md`](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/hld.md) (Agent dispatch), [`apps/chat-api/src/main.ts`](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/main.ts) (Chat API), [`apps/chat-api/src/app.module.ts`](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/app.module.ts) (API bootstrap), [`apps/web/src/app/page.tsx`](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/web/src/app/page.tsx) (Web client / BFF)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_web["Web client / BFF<br/>[page.tsx]"]
  node_conversation["Channels and DMs<br/>[product-brief.md]"]
end

subgraph group_chat["Chat API"]
  node_api["Chat API<br/>[main.ts]"]
  node_api_bootstrap["API bootstrap<br/>[app.module.ts]"]
  node_api_config["Environment config<br/>[config.module.ts]"]
  node_api_db["Database setup<br/>[database.module.ts]"]
  node_api_errors["Error responses"]
end

subgraph group_agents["Agent system"]
  node_agent_dispatch["Agent dispatch<br/>[hld.md]"]
  node_agent_plugins["Agent plugins<br/>[hld.md]"]
  node_agent_actions["Task delegation<br/>[product-brief.md]"]
  node_business_queries["Business data queries<br/>[product-brief.md]"]
end

subgraph group_platform["Data and services"]
  node_model{{"AI model provider"}}
  node_postgres[("PostgreSQL")]
  node_redis[("Redis")]
  node_s3[("PDF storage")]
end

node_person(("Chat user"))

node_person -->|"uses"| node_web
node_person -->|"connects by WebSocket"| node_api
node_web -->|"calls by REST"| node_api
node_web -->|"dispatches request"| node_agent_dispatch
node_conversation -.->|"mentions agent"| node_agent_dispatch
node_agent_dispatch -.->|"routes to plugin"| node_agent_plugins
node_agent_dispatch -->|"posts bot reply"| node_api
node_agent_dispatch -->|"requests inference"| node_model
node_agent_dispatch -->|"reads business data"| node_postgres
node_agent_dispatch -->|"uses queue and events"| node_redis
node_agent_dispatch -->|"stores PDF"| node_s3
node_agent_actions -.->|"invoked by agent"| node_agent_dispatch
node_business_queries -.->|"invoked by agent"| node_agent_dispatch
node_api -->|"persists chat data"| node_postgres
node_api -->|"uses queue and events"| node_redis
node_api -->|"starts"| node_api_bootstrap
node_api_bootstrap -->|"imports"| node_api_config
node_api_bootstrap -->|"imports"| node_api_db
node_api_bootstrap -->|"registers filter"| node_api_errors
node_api_config -.->|"provides config"| node_api_db

click node_web "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/web/src/app/page.tsx"
click node_conversation "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/product-brief.md"
click node_api "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/main.ts"
click node_api_bootstrap "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/app.module.ts"
click node_api_config "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/config/config.module.ts"
click node_api_db "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/database/database.module.ts"
click node_api_errors "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/common/errors/problem-details.filter.ts"
click node_agent_dispatch "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/hld.md"
click node_agent_plugins "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/hld.md"
click node_agent_actions "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/product-brief.md"
click node_business_queries "https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/product-brief.md"

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_web,node_conversation,node_person toneBlue
class node_api,node_api_bootstrap,node_api_config,node_api_db,node_api_errors toneAmber
class node_agent_dispatch,node_agent_plugins,node_agent_actions,node_business_queries toneMint
class node_model,node_postgres,node_redis,node_s3 toneRose
```

## Components

### Web client

- [Web client / BFF](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/web/src/app/page.tsx): `apps/web/src/app/page.tsx`
- [Channels and DMs](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/product-brief.md): `docs/product-brief.md`

### Chat API

- [Chat API](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/main.ts): `apps/chat-api/src/main.ts`
- [API bootstrap](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/app.module.ts): `apps/chat-api/src/app.module.ts`
- [Environment config](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/config/config.module.ts): `apps/chat-api/src/config/config.module.ts`
- [Database setup](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/database/database.module.ts): `apps/chat-api/src/database/database.module.ts`
- [Error responses](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/apps/chat-api/src/common/errors/problem-details.filter.ts): `apps/chat-api/src/common/errors/problem-details.filter.ts`

### Agent system

- [Agent dispatch](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/hld.md): `docs/hld.md`
- [Agent plugins](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/hld.md): `docs/hld.md`
- [Task delegation](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/product-brief.md): `docs/product-brief.md`
- [Business data queries](https://github.com/devfullcycle/imersao-ia1/blob/docs/roadmap/docs/product-brief.md): `docs/product-brief.md`

### Data and services

- **AI model provider**
- **PostgreSQL**
- **Redis**
- **PDF storage**

### Other components

- **Chat user**

## Connections

- Chat user → Web client / BFF: uses (evidence: `README.md`)
- Chat user → Chat API: connects by WebSocket (evidence: `README.md`)
- Web client / BFF → Chat API: calls by REST (evidence: `README.md`)
- Web client / BFF → Agent dispatch: dispatches request (evidence: `README.md`)
- Channels and DMs → Agent dispatch: mentions agent
- Agent dispatch → Agent plugins: routes to plugin
- Agent dispatch → Chat API: posts bot reply (evidence: `README.md`)
- Agent dispatch → AI model provider: requests inference (evidence: `README.md`)
- Agent dispatch → PostgreSQL: reads business data (evidence: `README.md`)
- Agent dispatch → Redis: uses queue and events (evidence: `README.md`)
- Agent dispatch → PDF storage: stores PDF (evidence: `README.md`)
- Task delegation → Agent dispatch: invoked by agent
- Business data queries → Agent dispatch: invoked by agent
- Chat API → PostgreSQL: persists chat data (evidence: `README.md`)
- Chat API → Redis: uses queue and events (evidence: `README.md`)
- Chat API → API bootstrap: starts (evidence: `apps/chat-api/src/main.ts`)
- API bootstrap → Environment config: imports (evidence: `apps/chat-api/src/app.module.ts`)
- API bootstrap → Database setup: imports (evidence: `apps/chat-api/src/app.module.ts`)
- API bootstrap → Error responses: registers filter (evidence: `apps/chat-api/src/app.module.ts`)
- Environment config → Database setup: provides config