# gabryeldsous/chatpersona architecture

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

- Interactive diagram: https://gitdiagram.com/gabryeldsous/chatpersona
- Repository: https://github.com/gabryeldsous/chatpersona

## Overview

Chat Persona is a REST API for user-managed AI characters and persistent, character-based conversations. The principal workflow is: a user authenticates, selects a character, starts a conversation, then sends or edits messages; the application obtains AI-generated replies and persists conversation history. User, character, and conversation use cases form the application layer, with repository adapters providing persistence and an AI gateway providing the model integration. The README documents JWT authorization and role-based access. Some use-case internals were not sampled, so links from those use cases to repositories and the AI gateway reflect documented behavior and architecture, not inspected call sites.

Main entry points: [`src/main/java/dev/gabryel/chatpersona/conversation/application/usecase`](https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/conversation/application/usecase) (Conversation use cases), [`src/main/java/dev/gabryel/chatpersona/user/application/api/UserController.java`](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/user/application/api/UserController.java) (User API), [`src/main/java/dev/gabryel/chatpersona/character/infrastructure/persistence/JpaCharacterRepositoryAdapter.java`](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/character/infrastructure/persistence/JpaCharacterRepositoryAdapter.java) (Character persistence), [`src/main/java/dev/gabryel/chatpersona/user/application/usecase`](https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/user/application/usecase) (User use cases)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity and access"]
  node_user_api["User API"]
  node_user_cases["User use cases"]
  node_jwt_security["JWT security"]
  node_user_store["User persistence"]
end

subgraph group_characters["Character management"]
  node_character_api["Character API"]
  node_character_cases["Character use cases"]
  node_character_store["Character persistence"]
end

subgraph group_chat["Conversation and messaging"]
  node_conversation_api["Conversation API"]
  node_conversation_cases["Conversation use cases"]
  node_conversation_store["Conversation persistence"]
  node_message_store["Message persistence"]
end

subgraph group_integrations["Runtime integrations"]
  node_ai_gateway["AI chat gateway"]
end

node_user(("User"))
node_ai_provider{{"LLM provider"}}
node_postgres[("PostgreSQL")]

node_user -->|"submits requests"| node_user_api
node_user_api -->|"dispatches"| node_user_cases
node_user_cases -->|"uses repository"| node_user_store
node_user_api -->|"uses authenticated identity"| node_jwt_security
node_user -->|"manages characters"| node_character_api
node_character_api -->|"dispatches"| node_character_cases
node_character_cases -->|"uses repository"| node_character_store
node_user -->|"starts and chats"| node_conversation_api
node_conversation_api -->|"dispatches"| node_conversation_cases
node_conversation_cases -->|"loads character"| node_character_store
node_conversation_cases -->|"uses repository"| node_conversation_store
node_conversation_cases -->|"reads and writes messages"| node_message_store
node_conversation_cases -->|"requests AI reply"| node_ai_gateway
node_ai_gateway -.->|"sends chat context"| node_ai_provider
node_user_store -->|"reads and writes"| node_postgres
node_character_store -->|"reads and writes"| node_postgres
node_conversation_store -->|"reads and writes"| node_postgres
node_message_store -->|"reads and writes"| node_postgres

click node_user_api "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/user/application/api/UserController.java"
click node_user_cases "https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/user/application/usecase"
click node_jwt_security "https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/user/infrastructure/security"
click node_user_store "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/user/infrastructure/persistence/JpaUserRepositoryAdapter.java"
click node_character_api "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/character/api/CharacterController.java"
click node_character_cases "https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/character/application/usecase"
click node_character_store "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/character/infrastructure/persistence/JpaCharacterRepositoryAdapter.java"
click node_conversation_api "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/application/api/ConversationController.java"
click node_conversation_cases "https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/conversation/application/usecase"
click node_conversation_store "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/persistence/conversation/JpaConversationRepositoryAdapter.java"
click node_message_store "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/persistence/message/JpaMessageRepositoryAdapter.java"
click node_ai_gateway "https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/ai/SpringAiChatGateway.java"

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_api,node_user_cases,node_jwt_security,node_user_store,node_user toneBlue
class node_character_api,node_character_cases,node_character_store,node_postgres toneAmber
class node_conversation_api,node_conversation_cases,node_conversation_store,node_message_store toneMint
class node_ai_gateway toneRose
class node_ai_provider toneIndigo
```

## Components

### Identity and access

- [User API](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/user/application/api/UserController.java): `src/main/java/dev/gabryel/chatpersona/user/application/api/UserController.java`
- [User use cases](https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/user/application/usecase): `src/main/java/dev/gabryel/chatpersona/user/application/usecase`
- [JWT security](https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/user/infrastructure/security): `src/main/java/dev/gabryel/chatpersona/user/infrastructure/security`
- [User persistence](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/user/infrastructure/persistence/JpaUserRepositoryAdapter.java): `src/main/java/dev/gabryel/chatpersona/user/infrastructure/persistence/JpaUserRepositoryAdapter.java`

### Character management

- [Character API](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/character/api/CharacterController.java): `src/main/java/dev/gabryel/chatpersona/character/api/CharacterController.java`
- [Character use cases](https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/character/application/usecase): `src/main/java/dev/gabryel/chatpersona/character/application/usecase`
- [Character persistence](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/character/infrastructure/persistence/JpaCharacterRepositoryAdapter.java): `src/main/java/dev/gabryel/chatpersona/character/infrastructure/persistence/JpaCharacterRepositoryAdapter.java`

### Conversation and messaging

- [Conversation API](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/application/api/ConversationController.java): `src/main/java/dev/gabryel/chatpersona/conversation/application/api/ConversationController.java`
- [Conversation use cases](https://github.com/gabryeldsous/chatpersona/tree/main/src/main/java/dev/gabryel/chatpersona/conversation/application/usecase): `src/main/java/dev/gabryel/chatpersona/conversation/application/usecase`
- [Conversation persistence](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/persistence/conversation/JpaConversationRepositoryAdapter.java): `src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/persistence/conversation/JpaConversationRepositoryAdapter.java`
- [Message persistence](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/persistence/message/JpaMessageRepositoryAdapter.java): `src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/persistence/message/JpaMessageRepositoryAdapter.java`

### Runtime integrations

- [AI chat gateway](https://github.com/gabryeldsous/chatpersona/blob/main/src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/ai/SpringAiChatGateway.java): `src/main/java/dev/gabryel/chatpersona/conversation/infrastructure/ai/SpringAiChatGateway.java`

### Other components

- **User**
- **LLM provider**
- **PostgreSQL**

## Connections

- User → User API: submits requests
- User API → User use cases: dispatches
- User use cases → User persistence: uses repository
- User API → JWT security: uses authenticated identity
- User → Character API: manages characters
- Character API → Character use cases: dispatches
- Character use cases → Character persistence: uses repository
- User → Conversation API: starts and chats
- Conversation API → Conversation use cases: dispatches
- Conversation use cases → Character persistence: loads character
- Conversation use cases → Conversation persistence: uses repository
- Conversation use cases → Message persistence: reads and writes messages
- Conversation use cases → AI chat gateway: requests AI reply
- AI chat gateway → LLM provider: sends chat context
- User persistence → PostgreSQL: reads and writes
- Character persistence → PostgreSQL: reads and writes
- Conversation persistence → PostgreSQL: reads and writes
- Message persistence → PostgreSQL: reads and writes