# ncp-1st/ncp-avatar architecture

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

- Interactive diagram: https://gitdiagram.com/ncp-1st/ncp-avatar
- Repository: https://github.com/ncp-1st/ncp-avatar

## Overview

Mediary is an AI diary and avatar-video application with calendar/history browsing, location-based memories, and personalized supportive chat. The main workflow is mixed-media entry, preprocessing, AI interpretation and clarification, draft review and approval, then narration/video rendering and storage. Separate branches cover counseling with diary context, calendar retrieval, and map messages. The graph combines sampled implementation links with explicitly documented README flows; unsampled integrations are represented only where documented.

Main entry points: [`backend/orchestration/diary_orchestrator.py`](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_orchestrator.py) (Diary orchestration), [`backend/orchestration/diary_media.py`](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_media.py) (Narration and video), [`backend/api/diary.py`](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/diary.py) (Diary API), [`backend/orchestration/diary_pipeline.py`](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_pipeline.py) (Input preprocessing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User experience"]
  node_diary_ui["Diary screen<br/>[diary.py]"]
  node_calendar_ui["Calendar screen<br/>[calendar.py]"]
  node_counsel_ui["Counsel screen<br/>[counsel.py]"]
  node_map_ui["Map screen<br/>[map.py]"]
end

subgraph group_diary["Diary workflow"]
  node_diary_api["Diary API<br/>[diary.py]"]
  node_input_pipeline["Input preprocessing<br/>[diary_pipeline.py]"]
  node_diary_flow["Diary orchestration"]
  node_diary_agent["Multimodal diary agent<br/>[hcx.py]"]
  node_diary_models["Diary workflow models<br/>[models.py]"]
  node_script_agent["Script generation<br/>[hcx.py]"]
  node_media_render["Narration and video<br/>[diary_media.py]"]
end

subgraph group_memory["Memory and discovery"]
  node_calendar_api["Calendar API<br/>[calendar.py]"]
  node_calendar_queries["Calendar queries"]
  node_maps_api["Maps API<br/>[maps.py]"]
  node_maps_store["Map message service<br/>[store.py]"]
end

subgraph group_support["Counseling"]
  node_counsel_api["Counsel API<br/>[counsel.py]"]
  node_counsel_flow["Counsel orchestration<br/>[counsel_flow.py]"]
  node_counsel_agent["Counsel agent<br/>[context_agent.py]"]
  node_knowledge["Diary knowledge search<br/>[diary_vector.py]"]
end

subgraph group_platform["Persistence and services"]
  node_repository["Diary persistence<br/>[sqlalchemy.py]"]
  node_database[("Relational database<br/>[models.py]")]
  node_object_storage["Object storage<br/>[ncp_object.py]"]
  node_speech["Speech recognition<br/>[clova.py]"]
  node_voice["Voice synthesis<br/>[clova_voice.py]"]
  node_avatar["Avatar renderer"]
  node_embedding["Embedding service<br/>[service.py]"]
end

node_user(("User"))

node_user -->|"records media"| node_diary_ui
node_diary_ui -->|"submits entries"| node_diary_api
node_diary_api -->|"preprocesses inputs"| node_input_pipeline
node_input_pipeline -->|"stores media"| node_object_storage
node_input_pipeline -->|"transcribes audio"| node_speech
node_diary_api -->|"handles chat and review"| node_diary_flow
node_diary_flow -->|"interprets context"| node_diary_agent
node_diary_flow -->|"uses workflow state"| node_diary_models
node_diary_flow -.->|"generates draft"| node_script_agent
node_diary_flow -.->|"saves approved version"| node_repository
node_diary_flow -->|"indexes approved diary"| node_embedding
node_diary_flow -->|"renders approved diary"| node_media_render
node_media_render -->|"synthesizes narration"| node_voice
node_media_render -->|"renders avatar video"| node_avatar
node_media_render -->|"stores outputs"| node_object_storage
node_media_render -->|"updates render records"| node_repository
node_repository -->|"reads and writes"| node_database
node_user -->|"browses history"| node_calendar_ui
node_calendar_ui -->|"requests diary history"| node_calendar_api
node_calendar_api -->|"fetches filtered entries"| node_calendar_queries
node_calendar_queries -->|"queries diary records"| node_database
node_user -->|"starts a conversation"| node_counsel_ui
node_counsel_ui -.->|"sends message"| node_counsel_api
node_counsel_api -.->|"routes counseling"| node_counsel_flow
node_counsel_flow -.->|"applies support guidance"| node_counsel_agent
node_counsel_flow -.->|"retrieves diary context"| node_knowledge
node_user -->|"places a memory"| node_map_ui
node_map_ui -.->|"sends location message"| node_maps_api
node_maps_api -->|"stores map message"| node_maps_store
node_maps_api -->|"persists location record"| node_database

click node_diary_ui "https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/diary.py"
click node_calendar_ui "https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/calendar.py"
click node_counsel_ui "https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/counsel.py"
click node_map_ui "https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/map.py"
click node_diary_api "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/diary.py"
click node_input_pipeline "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_pipeline.py"
click node_diary_flow "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_orchestrator.py"
click node_diary_agent "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/diary_chatbot/hcx.py"
click node_diary_models "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/diary_chatbot/models.py"
click node_script_agent "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/diary_chatbot/write_script/hcx.py"
click node_media_render "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_media.py"
click node_calendar_api "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/calendar.py"
click node_calendar_queries "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/repositories/calendar_repository.py"
click node_counsel_api "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/counsel.py"
click node_counsel_flow "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/counsel_flow.py"
click node_counsel_agent "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/counsel_chatbot/context_agent.py"
click node_knowledge "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/knowledge/diary_vector.py"
click node_maps_api "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/maps.py"
click node_maps_store "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/maps/store.py"
click node_repository "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/repositories/sqlalchemy.py"
click node_database "https://github.com/ncp-1st/ncp-avatar/blob/main/database/models.py"
click node_object_storage "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/storage/ncp_object.py"
click node_speech "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/speech/clova.py"
click node_voice "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/voice/clova_voice.py"
click node_avatar "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/avatar/huggingface_space.py"
click node_embedding "https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/embedding/service.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_diary_ui,node_calendar_ui,node_counsel_ui,node_map_ui,node_user toneBlue
class node_diary_api,node_input_pipeline,node_diary_flow,node_diary_agent,node_diary_models,node_script_agent,node_media_render toneAmber
class node_calendar_api,node_calendar_queries,node_maps_api,node_maps_store toneMint
class node_counsel_api,node_counsel_flow,node_counsel_agent,node_knowledge toneRose
class node_repository,node_database,node_object_storage,node_speech,node_voice,node_avatar,node_embedding toneIndigo
```

## Components

### User experience

- [Diary screen](https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/diary.py): `frontend/pages/diary.py`
- [Calendar screen](https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/calendar.py): `frontend/pages/calendar.py`
- [Counsel screen](https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/counsel.py): `frontend/pages/counsel.py`
- [Map screen](https://github.com/ncp-1st/ncp-avatar/blob/main/frontend/pages/map.py): `frontend/pages/map.py`

### Diary workflow

- [Diary API](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/diary.py): `backend/api/diary.py`
- [Input preprocessing](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_pipeline.py): `backend/orchestration/diary_pipeline.py`
- [Diary orchestration](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_orchestrator.py): `backend/orchestration/diary_orchestrator.py`
- [Multimodal diary agent](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/diary_chatbot/hcx.py): `backend/agents/diary_chatbot/hcx.py`
- [Diary workflow models](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/diary_chatbot/models.py): `backend/agents/diary_chatbot/models.py`
- [Script generation](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/diary_chatbot/write_script/hcx.py): `backend/agents/diary_chatbot/write_script/hcx.py`
- [Narration and video](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/diary_media.py): `backend/orchestration/diary_media.py`

### Memory and discovery

- [Calendar API](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/calendar.py): `backend/api/calendar.py`
- [Calendar queries](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/repositories/calendar_repository.py): `backend/repositories/calendar_repository.py`
- [Maps API](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/maps.py): `backend/api/maps.py`
- [Map message service](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/maps/store.py): `backend/services/maps/store.py`

### Counseling

- [Counsel API](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/api/counsel.py): `backend/api/counsel.py`
- [Counsel orchestration](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/orchestration/counsel_flow.py): `backend/orchestration/counsel_flow.py`
- [Counsel agent](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/agents/counsel_chatbot/context_agent.py): `backend/agents/counsel_chatbot/context_agent.py`
- [Diary knowledge search](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/knowledge/diary_vector.py): `backend/services/knowledge/diary_vector.py`

### Persistence and services

- [Diary persistence](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/repositories/sqlalchemy.py): `backend/repositories/sqlalchemy.py`
- [Relational database](https://github.com/ncp-1st/ncp-avatar/blob/main/database/models.py): `database/models.py`
- [Object storage](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/storage/ncp_object.py): `backend/services/storage/ncp_object.py`
- [Speech recognition](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/speech/clova.py): `backend/services/speech/clova.py`
- [Voice synthesis](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/voice/clova_voice.py): `backend/services/voice/clova_voice.py`
- [Avatar renderer](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/avatar/huggingface_space.py): `backend/services/avatar/huggingface_space.py`
- [Embedding service](https://github.com/ncp-1st/ncp-avatar/blob/main/backend/services/embedding/service.py): `backend/services/embedding/service.py`

### Other components

- **User**

## Connections

- User → Diary screen: records media (evidence: `README.md`)
- Diary screen → Diary API: submits entries (evidence: `frontend/pages/diary.py`)
- Diary API → Input preprocessing: preprocesses inputs (evidence: `backend/api/diary.py`)
- Input preprocessing → Object storage: stores media (evidence: `backend/orchestration/diary_pipeline.py`)
- Input preprocessing → Speech recognition: transcribes audio (evidence: `backend/orchestration/diary_pipeline.py`)
- Diary API → Diary orchestration: handles chat and review (evidence: `backend/api/diary.py`)
- Diary orchestration → Multimodal diary agent: interprets context (evidence: `backend/orchestration/diary_orchestrator.py`)
- Diary orchestration → Diary workflow models: uses workflow state (evidence: `backend/orchestration/diary_orchestrator.py`)
- Diary orchestration → Script generation: generates draft
- Diary orchestration → Diary persistence: saves approved version
- Diary orchestration → Embedding service: indexes approved diary (evidence: `backend/orchestration/diary_orchestrator.py`)
- Diary orchestration → Narration and video: renders approved diary (evidence: `backend/orchestration/diary_orchestrator.py`)
- Narration and video → Voice synthesis: synthesizes narration (evidence: `backend/orchestration/diary_media.py`)
- Narration and video → Avatar renderer: renders avatar video (evidence: `backend/orchestration/diary_media.py`)
- Narration and video → Object storage: stores outputs (evidence: `backend/orchestration/diary_media.py`)
- Narration and video → Diary persistence: updates render records (evidence: `backend/orchestration/diary_media.py`)
- Diary persistence → Relational database: reads and writes (evidence: `backend/repositories/sqlalchemy.py`)
- User → Calendar screen: browses history (evidence: `README.md`)
- Calendar screen → Calendar API: requests diary history (evidence: `frontend/pages/calendar.py`)
- Calendar API → Calendar queries: fetches filtered entries (evidence: `backend/api/calendar.py`)
- Calendar queries → Relational database: queries diary records (evidence: `backend/repositories/calendar_repository.py`)
- User → Counsel screen: starts a conversation (evidence: `README.md`)
- Counsel screen → Counsel API: sends message
- Counsel API → Counsel orchestration: routes counseling
- Counsel orchestration → Counsel agent: applies support guidance
- Counsel orchestration → Diary knowledge search: retrieves diary context
- User → Map screen: places a memory (evidence: `README.md`)
- Map screen → Maps API: sends location message
- Maps API → Map message service: stores map message (evidence: `backend/api/maps.py`)
- Maps API → Relational database: persists location record (evidence: `backend/api/maps.py`)
