# elixzon/friendship-communication-app architecture

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

- Interactive diagram: https://gitdiagram.com/elixzon/friendship-communication-app
- Repository: https://github.com/elixzon/friendship-communication-app

## Overview

Friendship Communication is a paired, code-based experience for friends to answer prompts privately and receive relationship-level reflections. The main journey is create or join a session, give consent, start a question round, submit answers, synchronize progress, and view generated insights. The frontend manages session state and presents the experience; FastAPI routes coordinate session services and persistence. The tree and excerpts establish the session and WebSocket paths, but do not fully expose answer/insight orchestration, so those links are limited to supported evidence.

Main entry points: [`app/routes/session_routes.py`](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/routes/session_routes.py) (Session endpoints), [`frontend/src/contexts/InviteContext.tsx`](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/contexts/InviteContext.tsx) (Invite state), [`app/main.py`](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/main.py) (API application), [`app/services/session_service.py`](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/session_service.py) (Session lifecycle)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Friendship experience"]
  node_web["Web experience<br/>[index.tsx]"]
  node_invite["Invite flows<br/>[index.tsx]"]
  node_session_ui["Session room<br/>[session.tsx]"]
  node_invite_state["Invite state<br/>[InviteContext.tsx]"]
  node_api_client["HTTP client<br/>[api.ts]"]
  node_ws_client["WebSocket client<br/>[websocket.ts]"]
end

subgraph group_backend["Session backend"]
  node_app["API application<br/>[main.py]"]
  node_session_routes["Session endpoints<br/>[session_routes.py]"]
  node_database_layer["Database access<br/>[database.py]"]
end

subgraph group_domain["Session domain"]
  node_session_service["Session lifecycle<br/>[session_service.py]"]
  node_question_service["Question flow"]
  node_answer_service["Answer handling<br/>[answer_service.py]"]
  node_insight_service["Insight generation<br/>[insight_service.py]"]
  node_question_bank["Question bank<br/>[questions.py]"]
end

subgraph group_realtime["Live updates"]
  node_ws_routes["WebSocket endpoint<br/>[routes.py]"]
  node_ws_manager["Connection manager<br/>[manager.py]"]
end

node_participant(("Friend"))
node_mongo[("MongoDB")]
node_gemini["Gemini API"]

node_participant -->|"opens"| node_web
node_participant -->|"creates or joins"| node_invite
node_invite -->|"updates session"| node_invite_state
node_session_ui -->|"reads session"| node_invite_state
node_invite_state -->|"requests session"| node_api_client
node_api_client -->|"HTTP requests"| node_app
node_app -->|"dispatches"| node_session_routes
node_session_routes -->|"calls lifecycle"| node_session_service
node_session_service -->|"reads and writes"| node_database_layer
node_database_layer -->|"queries"| node_mongo
node_session_service -->|"selects questions"| node_question_service
node_question_service -->|"selects from"| node_question_bank
node_session_routes -->|"broadcasts events"| node_ws_manager
node_invite_state -->|"opens connection"| node_ws_client
node_ws_client -->|"connects"| node_ws_routes
node_app -->|"dispatches"| node_ws_routes
node_ws_routes -->|"registers connection"| node_ws_manager
node_session_routes -.->|"answer workflow"| node_answer_service
node_session_routes -.->|"insight workflow"| node_insight_service
node_insight_service -->|"requests generation"| node_gemini

click node_web "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/pages/index.tsx"
click node_invite "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/pages/invite/index.tsx"
click node_session_ui "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/pages/session.tsx"
click node_invite_state "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/contexts/InviteContext.tsx"
click node_api_client "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/api.ts"
click node_ws_client "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/websocket.ts"
click node_app "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/main.py"
click node_session_routes "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/routes/session_routes.py"
click node_ws_routes "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/websocket/routes.py"
click node_ws_manager "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/websocket/manager.py"
click node_session_service "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/session_service.py"
click node_question_service "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/question_service.py"
click node_answer_service "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/answer_service.py"
click node_insight_service "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/insight_service.py"
click node_question_bank "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/data/questions.py"
click node_database_layer "https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/database.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_web,node_invite,node_session_ui,node_invite_state,node_api_client,node_ws_client toneBlue
class node_app,node_session_routes,node_database_layer,node_mongo toneAmber
class node_session_service,node_question_service,node_answer_service,node_insight_service,node_question_bank,node_gemini toneMint
class node_ws_routes,node_ws_manager toneRose
class node_participant toneIndigo
```

## Components

### Friendship experience

- [Web experience](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/pages/index.tsx): `frontend/pages/index.tsx`
- [Invite flows](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/pages/invite/index.tsx): `frontend/pages/invite/index.tsx`
- [Session room](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/pages/session.tsx): `frontend/pages/session.tsx`
- [Invite state](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/contexts/InviteContext.tsx): `frontend/src/contexts/InviteContext.tsx`
- [HTTP client](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/api.ts): `frontend/src/api.ts`
- [WebSocket client](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/frontend/src/websocket.ts): `frontend/src/websocket.ts`

### Session backend

- [API application](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/main.py): `app/main.py`
- [Session endpoints](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/routes/session_routes.py): `app/routes/session_routes.py`
- [Database access](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/database.py): `app/database.py`

### Session domain

- [Session lifecycle](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/session_service.py): `app/services/session_service.py`
- [Question flow](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/question_service.py): `app/services/question_service.py`
- [Answer handling](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/answer_service.py): `app/services/answer_service.py`
- [Insight generation](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/services/insight_service.py): `app/services/insight_service.py`
- [Question bank](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/data/questions.py): `app/data/questions.py`

### Live updates

- [WebSocket endpoint](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/websocket/routes.py): `app/websocket/routes.py`
- [Connection manager](https://github.com/elixzon/friendship-communication-app/blob/friendship-v2/app/websocket/manager.py): `app/websocket/manager.py`

### Other components

- **Friend**
- **MongoDB**
- **Gemini API**

## Connections

- Friend → Web experience: opens
- Friend → Invite flows: creates or joins
- Invite flows → Invite state: updates session
- Session room → Invite state: reads session
- Invite state → HTTP client: requests session
- HTTP client → API application: HTTP requests
- API application → Session endpoints: dispatches
- Session endpoints → Session lifecycle: calls lifecycle
- Session lifecycle → Database access: reads and writes
- Database access → MongoDB: queries
- Session lifecycle → Question flow: selects questions
- Question flow → Question bank: selects from
- Session endpoints → Connection manager: broadcasts events
- Invite state → WebSocket client: opens connection
- WebSocket client → WebSocket endpoint: connects
- API application → WebSocket endpoint: dispatches
- WebSocket endpoint → Connection manager: registers connection
- Session endpoints → Answer handling: answer workflow
- Session endpoints → Insight generation: insight workflow
- Insight generation → Gemini API: requests generation