# michaelis2101/amd-hackaton architecture

> Architecture diagram of the GitHub repository michaelis2101/amd-hackaton, 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/michaelis2101/amd-hackaton
- Repository: https://github.com/michaelis2101/amd-hackaton

## Overview

This repository contains a chat backend, a separate AI-agent service, and platform runner shells for a Flutter client; the client’s Dart application code is not present in the supplied tree. The main evidenced workflow is a chat question routed through knowledge retrieval and embeddings, sent to the agent, then saved with citations and an AI log. Chat, profile, and document-ingestion capabilities are visible from module names and sampled services, but their router wiring and the agent’s internal execution are not shown, so those links are omitted.

Main entry points: [`API/app/main.py`](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/main.py) (API application), [`API/app/database.py`](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/database.py) (Database access), [`API/app/services/ai_service.py`](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/ai_service.py) (Answer service), [`Agent/app/main.py`](https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/main.py) (Agent API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API access"]
  node_api_app["API application<br/>[main.py]"]
  node_auth["API key auth<br/>[auth.py]"]
end

subgraph group_collaboration["Chat and profiles"]
  node_chat_routes["Chat routes<br/>[chat.py]"]
  node_chat_service["Chat service<br/>[chat_service.py]"]
  node_profile_routes["Profile routes<br/>[profiles.py]"]
  node_profile_service["Profile service<br/>[profile_service.py]"]
  node_chat_db["Database access<br/>[database.py]"]
  node_models["Domain models<br/>[models.py]"]
end

subgraph group_knowledge["Knowledge retrieval"]
  node_knowledge_routes["Knowledge routes<br/>[knowledge.py]"]
  node_knowledge_service["Knowledge service"]
  node_embedding_service["Embedding service"]
end

subgraph group_agent["AI agent"]
  node_ai_routes["AI routes<br/>[ai.py]"]
  node_ai_service["Answer service<br/>[ai_service.py]"]
  node_agent_app["Agent API<br/>[main.py]"]
  node_agent_router["Agent endpoint<br/>[api.py]"]
  node_agent_logic["Agent logic<br/>[agent.py]"]
  node_agent_auth["Agent key auth<br/>[auth.py]"]
end

node_user(("Client user"))
node_postgres[("PostgreSQL")]
node_gemini_embed["Gemini embeddings"]
node_agent_service["Agent service"]

node_user -->|"sends requests"| node_api_app
node_api_app -->|"checks keys"| node_auth
node_api_app -->|"mounts routes"| node_chat_routes
node_api_app -->|"mounts routes"| node_profile_routes
node_api_app -->|"mounts routes"| node_knowledge_routes
node_api_app -->|"mounts routes"| node_ai_routes
node_chat_service -->|"uses sessions"| node_chat_db
node_profile_service -->|"uses sessions"| node_chat_db
node_knowledge_service -->|"requests vectors"| node_embedding_service
node_embedding_service -->|"embeds text"| node_gemini_embed
node_ai_service -->|"searches knowledge"| node_knowledge_service
node_ai_service -->|"sends prompt"| node_agent_service
node_ai_service -->|"saves answer and log"| node_chat_db
node_agent_service -->|"HTTP request"| node_agent_app
node_agent_app -->|"mounts router"| node_agent_router
node_agent_app -->|"checks keys"| node_agent_auth
node_chat_db -->|"maps entities"| node_models
node_chat_db -->|"reads and writes"| node_postgres

click node_api_app "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/main.py"
click node_auth "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/auth.py"
click node_chat_routes "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/chat.py"
click node_chat_service "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/chat_service.py"
click node_profile_routes "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/profiles.py"
click node_profile_service "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/profile_service.py"
click node_chat_db "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/database.py"
click node_models "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/models.py"
click node_knowledge_routes "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/knowledge.py"
click node_knowledge_service "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/knowledge_service.py"
click node_embedding_service "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/embedding_service.py"
click node_ai_routes "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/ai.py"
click node_ai_service "https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/ai_service.py"
click node_agent_app "https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/main.py"
click node_agent_router "https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/api.py"
click node_agent_logic "https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/agent.py"
click node_agent_auth "https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/tools/auth.py"

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_api_app,node_auth,node_user toneBlue
class node_chat_routes,node_chat_service,node_profile_routes,node_profile_service,node_chat_db,node_models,node_postgres toneAmber
class node_knowledge_routes,node_knowledge_service,node_embedding_service toneMint
class node_ai_routes,node_ai_service,node_agent_app,node_agent_router,node_agent_logic,node_agent_auth toneRose
class node_gemini_embed,node_agent_service toneIndigo
```

## Components

### API access

- [API application](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/main.py): `API/app/main.py`
- [API key auth](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/auth.py): `API/app/auth.py`

### Chat and profiles

- [Chat routes](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/chat.py): `API/app/routers/chat.py`
- [Chat service](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/chat_service.py): `API/app/services/chat_service.py`
- [Profile routes](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/profiles.py): `API/app/routers/profiles.py`
- [Profile service](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/profile_service.py): `API/app/services/profile_service.py`
- [Database access](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/database.py): `API/app/database.py`
- [Domain models](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/models.py): `API/app/models.py`

### Knowledge retrieval

- [Knowledge routes](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/knowledge.py): `API/app/routers/knowledge.py`
- [Knowledge service](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/knowledge_service.py): `API/app/services/knowledge_service.py`
- [Embedding service](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/embedding_service.py): `API/app/services/embedding_service.py`

### AI agent

- [AI routes](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/routers/ai.py): `API/app/routers/ai.py`
- [Answer service](https://github.com/michaelis2101/amd-hackaton/blob/main/API/app/services/ai_service.py): `API/app/services/ai_service.py`
- [Agent API](https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/main.py): `Agent/app/main.py`
- [Agent endpoint](https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/api.py): `Agent/app/api.py`
- [Agent logic](https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/agent.py): `Agent/app/agent.py`
- [Agent key auth](https://github.com/michaelis2101/amd-hackaton/blob/main/Agent/app/tools/auth.py): `Agent/app/tools/auth.py`

### Other components

- **Client user**
- **PostgreSQL**
- **Gemini embeddings**
- **Agent service**

## Connections

- Client user → API application: sends requests
- API application → API key auth: checks keys
- API application → Chat routes: mounts routes
- API application → Profile routes: mounts routes
- API application → Knowledge routes: mounts routes
- API application → AI routes: mounts routes
- Chat service → Database access: uses sessions
- Profile service → Database access: uses sessions
- Knowledge service → Embedding service: requests vectors
- Embedding service → Gemini embeddings: embeds text
- Answer service → Knowledge service: searches knowledge
- Answer service → Agent service: sends prompt
- Answer service → Database access: saves answer and log
- Agent service → Agent API: HTTP request
- Agent API → Agent endpoint: mounts router
- Agent API → Agent key auth: checks keys
- Database access → Domain models: maps entities
- Database access → PostgreSQL: reads and writes