# susesh10/project-aether-js architecture

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

- Interactive diagram: https://gitdiagram.com/susesh10/project-aether-js
- Repository: https://github.com/susesh10/project-aether-js

## Overview

Project Aether is a personal AI companion: users chat through a React interface, and FastAPI routes messages to Akari’s Groq-backed reply service. The backend also extracts durable user facts, stores memory and tasks in MongoDB, and exposes search, task, memory-reset, and speech endpoints. The frontend has browser speech recognition and requests spoken replies. Blender assets represent a separate, early character-modeling effort; the README describes references and head-stage files, but no runtime integration. The graph follows shown calls and documented capabilities; unsampled Blender and frontend styling internals are not inferred.

Main entry points: [`backend/app/main.py`](https://github.com/susesh10/project-aether-js/blob/main/backend/app/main.py) (FastAPI routes), [`backend/app/services/ai.py`](https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/ai.py) (AI reply service), [`frontend/src/App.tsx`](https://github.com/susesh10/project-aether-js/blob/main/frontend/src/App.tsx) (Chat UI), [`backend/app/core/database.py`](https://github.com/susesh10/project-aether-js/blob/main/backend/app/core/database.py) (MongoDB connection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Chat interface"]
  node_ui["Chat UI<br/>[App.tsx]"]
end

subgraph group_backend["Conversation services"]
  node_api["FastAPI routes<br/>[main.py]"]
  node_chat_schema["Chat schema<br/>[chat.py]"]
  node_reply["AI reply service<br/>[ai.py]"]
  node_config["Runtime settings<br/>[config.py]"]
  node_tools["Search and time tools<br/>[tools.py]"]
  node_voice["Speech synthesis<br/>[voice.py]"]
end

subgraph group_memory["Memory and tasks"]
  node_extractor["Fact extraction"]
  node_memory_service["Memory and tasks<br/>[memory.py]"]
  node_database["MongoDB connection<br/>[database.py]"]
end

subgraph group_assets["Character assets"]
  node_blender_refs["Character references"]
  node_blender_head["Head model files"]
end

node_user(("Companion user"))
node_groq{{"Groq LLM"}}
node_mongo[("MongoDB")]
node_searx{{"SearxNG"}}
node_speech_service{{"Edge TTS"}}
node_browser_speech{{"Browser speech recognition"}}

node_user -->|"sends messages"| node_ui
node_ui -->|"posts chat"| node_api
node_api -->|"validates requests"| node_chat_schema
node_api -->|"requests reply"| node_reply
node_reply -->|"calls model"| node_groq
node_reply -->|"resolves model"| node_config
node_api -->|"extracts facts"| node_extractor
node_api -->|"reads and updates"| node_memory_service
node_reply -->|"uses memory and tasks"| node_memory_service
node_memory_service -->|"uses collection"| node_database
node_database -->|"loads connection settings"| node_config
node_database -->|"connects to"| node_mongo
node_reply -->|"dispatches tools"| node_tools
node_tools -->|"queries search"| node_searx
node_api -->|"serves search"| node_tools
node_ui -->|"requests speech and reset"| node_api
node_api -->|"generates speech"| node_voice
node_voice -->|"synthesizes audio"| node_speech_service
node_ui -->|"recognizes voice input"| node_browser_speech
node_blender_refs -.->|"informs modeling"| node_blender_head

click node_ui "https://github.com/susesh10/project-aether-js/blob/main/frontend/src/App.tsx"
click node_api "https://github.com/susesh10/project-aether-js/blob/main/backend/app/main.py"
click node_chat_schema "https://github.com/susesh10/project-aether-js/blob/main/backend/app/schemas/chat.py"
click node_reply "https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/ai.py"
click node_config "https://github.com/susesh10/project-aether-js/blob/main/backend/app/core/config.py"
click node_extractor "https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/memory_extractor.py"
click node_memory_service "https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/memory.py"
click node_database "https://github.com/susesh10/project-aether-js/blob/main/backend/app/core/database.py"
click node_tools "https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/tools.py"
click node_voice "https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/voice.py"
click node_blender_refs "https://github.com/susesh10/project-aether-js/tree/main/Blender/references"
click node_blender_head "https://github.com/susesh10/project-aether-js/tree/main/Blender/Akari_model/head"

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_ui,node_user,node_browser_speech toneBlue
class node_api,node_chat_schema,node_reply,node_config,node_tools,node_voice,node_mongo toneAmber
class node_extractor,node_memory_service,node_database toneMint
class node_blender_refs,node_blender_head toneRose
class node_groq,node_searx,node_speech_service toneIndigo
```

## Components

### Chat interface

- [Chat UI](https://github.com/susesh10/project-aether-js/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Conversation services

- [FastAPI routes](https://github.com/susesh10/project-aether-js/blob/main/backend/app/main.py): `backend/app/main.py`
- [Chat schema](https://github.com/susesh10/project-aether-js/blob/main/backend/app/schemas/chat.py): `backend/app/schemas/chat.py`
- [AI reply service](https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/ai.py): `backend/app/services/ai.py`
- [Runtime settings](https://github.com/susesh10/project-aether-js/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [Search and time tools](https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/tools.py): `backend/app/services/tools.py`
- [Speech synthesis](https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/voice.py): `backend/app/services/voice.py`

### Memory and tasks

- [Fact extraction](https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/memory_extractor.py): `backend/app/services/memory_extractor.py`
- [Memory and tasks](https://github.com/susesh10/project-aether-js/blob/main/backend/app/services/memory.py): `backend/app/services/memory.py`
- [MongoDB connection](https://github.com/susesh10/project-aether-js/blob/main/backend/app/core/database.py): `backend/app/core/database.py`

### Character assets

- [Character references](https://github.com/susesh10/project-aether-js/tree/main/Blender/references): `Blender/references`
- [Head model files](https://github.com/susesh10/project-aether-js/tree/main/Blender/Akari_model/head): `Blender/Akari_model/head`

### Other components

- **Companion user**
- **Groq LLM**
- **MongoDB**
- **SearxNG**
- **Edge TTS**
- **Browser speech recognition**

## Connections

- Companion user → Chat UI: sends messages (evidence: `frontend/src/App.tsx`)
- Chat UI → FastAPI routes: posts chat (evidence: `frontend/src/App.tsx`)
- FastAPI routes → Chat schema: validates requests (evidence: `backend/app/main.py`)
- FastAPI routes → AI reply service: requests reply (evidence: `backend/app/main.py`)
- AI reply service → Groq LLM: calls model (evidence: `backend/app/services/ai.py`)
- AI reply service → Runtime settings: resolves model (evidence: `backend/app/services/ai.py`)
- FastAPI routes → Fact extraction: extracts facts (evidence: `backend/app/main.py`)
- FastAPI routes → Memory and tasks: reads and updates (evidence: `backend/app/main.py`)
- AI reply service → Memory and tasks: uses memory and tasks (evidence: `backend/app/services/ai.py`)
- Memory and tasks → MongoDB connection: uses collection (evidence: `backend/app/services/memory.py`)
- MongoDB connection → Runtime settings: loads connection settings (evidence: `backend/app/core/database.py`)
- MongoDB connection → MongoDB: connects to (evidence: `backend/app/core/database.py`)
- AI reply service → Search and time tools: dispatches tools (evidence: `backend/app/services/ai.py`)
- Search and time tools → SearxNG: queries search (evidence: `backend/app/services/tools.py`)
- FastAPI routes → Search and time tools: serves search (evidence: `backend/app/main.py`)
- Chat UI → FastAPI routes: requests speech and reset (evidence: `frontend/src/App.tsx`)
- FastAPI routes → Speech synthesis: generates speech (evidence: `backend/app/main.py`)
- Speech synthesis → Edge TTS: synthesizes audio (evidence: `backend/app/services/voice.py`)
- Chat UI → Browser speech recognition: recognizes voice input (evidence: `frontend/src/App.tsx`)
- Character references → Head model files: informs modeling (evidence: `README.md`)
