# tanvi-vasoya/tripconsensus architecture

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

- Interactive diagram: https://gitdiagram.com/tanvi-vasoya/tripconsensus
- Repository: https://github.com/tanvi-vasoya/tripconsensus

## Overview

TripConsensus coordinates group trip planning from trip creation and participant preference collection to AI destination suggestions and a group vote. Participants can submit preferences through a web form or an SMS survey; the README notes that the inbound SMS webhook is not yet connected to survey processing. The graph highlights the service-owned workflow, persistence, AI gateway, and ranked-choice stage. Connections for unsampled routes and services rely on README descriptions rather than inspected implementations.

Main entry points: [`app/repositories`](https://github.com/tanvi-vasoya/tripconsensus/tree/main/app/repositories) (Repositories), [`app/services/recommendation_service.py`](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/recommendation_service.py) (Recommendation orchestration), [`app/main.py`](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/main.py) (FastAPI app), [`app/services/survey_service.py`](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/survey_service.py) (SMS survey service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Application entry"]
  node_main["FastAPI app<br/>[main.py]"]
  node_trip_api["Trip routes<br/>[trips.py]"]
  node_survey_api["Web survey routes<br/>[survey.py]"]
  node_sms_api["SMS webhook<br/>[sms_webhook.py]"]
  node_recommendation_api["Recommendation routes<br/>[recommendations.py]"]
  node_vote_api["Vote routes<br/>[votes.py]"]
end

subgraph group_planning["Trip and preferences"]
  node_trip_service["Trip orchestration<br/>[trip_service.py]"]
  node_survey_service["SMS survey service<br/>[survey_service.py]"]
  node_web_survey["Web survey service"]
  node_survey_engine["Survey engine<br/>[engine.py]"]
  node_sms_service["SMS messaging<br/>[sms_service.py]"]
end

subgraph group_recommendations["AI recommendations"]
  node_recommendation_service["Recommendation orchestration"]
  node_prompt_renderer["Prompt renderer<br/>[renderer.py]"]
  node_ai_gateway["AI gateway<br/>[gateway.py]"]
  node_ollama["Ollama provider<br/>[ollama_provider.py]"]
  node_parser["Recommendation parser"]
end

subgraph group_voting["Voting"]
  node_voting_service["Voting orchestration<br/>[voting_service.py]"]
  node_ranked_choice["Ranked-choice algorithm<br/>[ranked_choice.py]"]
end

subgraph group_persistence["Persistence and integrations"]
  node_twilio["Twilio client<br/>[twilio_client.py]"]
  node_repositories["Repositories"]
  node_database[("Database sessions<br/>[database.py]")]
end

node_user(("Trip planner"))
node_sms_provider["Twilio SMS"]
node_llm["LLM service"]
node_postgres[("PostgreSQL")]

node_user -->|"creates trip"| node_trip_api
node_main -->|"registers"| node_trip_api
node_main -->|"registers"| node_survey_api
node_main -->|"registers"| node_sms_api
node_main -->|"registers"| node_recommendation_api
node_main -->|"registers"| node_vote_api
node_trip_api -->|"delegates to"| node_trip_service
node_survey_api -->|"submits answers"| node_web_survey
node_sms_api -.->|"pending wiring"| node_survey_service
node_trip_service -->|"persists trip"| node_repositories
node_trip_service -->|"sends invitations"| node_sms_service
node_survey_service -->|"validates answers"| node_survey_engine
node_survey_service -->|"saves responses"| node_repositories
node_survey_service -->|"sends questions"| node_sms_service
node_web_survey -->|"saves responses"| node_repositories
node_sms_service -->|"uses client"| node_twilio
node_twilio -->|"sends SMS"| node_sms_provider
node_recommendation_api -->|"delegates to"| node_recommendation_service
node_recommendation_service -->|"loads trip and surveys"| node_repositories
node_recommendation_service -->|"renders prompt"| node_prompt_renderer
node_recommendation_service -->|"requests generation"| node_ai_gateway
node_ai_gateway -->|"dispatches to"| node_ollama
node_ollama -->|"sends inference request"| node_llm
node_recommendation_service -->|"parses response"| node_parser
node_recommendation_service -->|"replaces recommendations"| node_repositories
node_vote_api -->|"delegates to"| node_voting_service
node_voting_service -->|"reads and writes votes"| node_repositories
node_voting_service -->|"runs election"| node_ranked_choice
node_repositories -->|"queries session"| node_database
node_database -->|"connects to"| node_postgres

click node_main "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/main.py"
click node_trip_api "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/trips.py"
click node_survey_api "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/survey.py"
click node_sms_api "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/sms_webhook.py"
click node_recommendation_api "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/recommendations.py"
click node_vote_api "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/votes.py"
click node_trip_service "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/trip_service.py"
click node_survey_service "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/survey_service.py"
click node_web_survey "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/web_survey_service.py"
click node_survey_engine "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/survey/engine.py"
click node_sms_service "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/sms_service.py"
click node_twilio "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/sms/twilio_client.py"
click node_recommendation_service "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/recommendation_service.py"
click node_prompt_renderer "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/prompts/renderer.py"
click node_ai_gateway "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/gateway/gateway.py"
click node_ollama "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/gateway/providers/ollama_provider.py"
click node_parser "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/ai/recommendation_parser.py"
click node_voting_service "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/voting_service.py"
click node_ranked_choice "https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/algorithms/ranked_choice.py"
click node_repositories "https://github.com/tanvi-vasoya/tripconsensus/tree/main/app/repositories"
click node_database "https://github.com/tanvi-vasoya/tripconsensus/blob/main/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_main,node_trip_api,node_survey_api,node_sms_api,node_recommendation_api,node_vote_api toneBlue
class node_trip_service,node_survey_service,node_web_survey,node_survey_engine,node_sms_service,node_postgres toneAmber
class node_recommendation_service,node_prompt_renderer,node_ai_gateway,node_ollama,node_parser toneMint
class node_voting_service,node_ranked_choice toneRose
class node_twilio,node_repositories,node_database,node_user,node_sms_provider,node_llm toneIndigo
```

## Components

### Application entry

- [FastAPI app](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/main.py): `app/main.py`
- [Trip routes](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/trips.py): `app/api/trips.py`
- [Web survey routes](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/survey.py): `app/api/survey.py`
- [SMS webhook](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/sms_webhook.py): `app/api/sms_webhook.py`
- [Recommendation routes](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/recommendations.py): `app/api/recommendations.py`
- [Vote routes](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/api/votes.py): `app/api/votes.py`

### Trip and preferences

- [Trip orchestration](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/trip_service.py): `app/services/trip_service.py`
- [SMS survey service](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/survey_service.py): `app/services/survey_service.py`
- [Web survey service](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/web_survey_service.py): `app/services/web_survey_service.py`
- [Survey engine](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/survey/engine.py): `app/survey/engine.py`
- [SMS messaging](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/sms_service.py): `app/services/sms_service.py`

### AI recommendations

- [Recommendation orchestration](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/recommendation_service.py): `app/services/recommendation_service.py`
- [Prompt renderer](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/prompts/renderer.py): `app/prompts/renderer.py`
- [AI gateway](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/gateway/gateway.py): `app/gateway/gateway.py`
- [Ollama provider](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/gateway/providers/ollama_provider.py): `app/gateway/providers/ollama_provider.py`
- [Recommendation parser](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/ai/recommendation_parser.py): `app/ai/recommendation_parser.py`

### Voting

- [Voting orchestration](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/services/voting_service.py): `app/services/voting_service.py`
- [Ranked-choice algorithm](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/algorithms/ranked_choice.py): `app/algorithms/ranked_choice.py`

### Persistence and integrations

- [Twilio client](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/sms/twilio_client.py): `app/sms/twilio_client.py`
- [Repositories](https://github.com/tanvi-vasoya/tripconsensus/tree/main/app/repositories): `app/repositories`
- [Database sessions](https://github.com/tanvi-vasoya/tripconsensus/blob/main/app/database.py): `app/database.py`

### Other components

- **Trip planner**
- **Twilio SMS**
- **LLM service**
- **PostgreSQL**

## Connections

- Trip planner → Trip routes: creates trip
- FastAPI app → Trip routes: registers (evidence: `app/main.py`)
- FastAPI app → Web survey routes: registers (evidence: `app/main.py`)
- FastAPI app → SMS webhook: registers (evidence: `app/main.py`)
- FastAPI app → Recommendation routes: registers (evidence: `app/main.py`)
- FastAPI app → Vote routes: registers (evidence: `app/main.py`)
- Trip routes → Trip orchestration: delegates to
- Web survey routes → Web survey service: submits answers
- SMS webhook → SMS survey service: pending wiring
- Trip orchestration → Repositories: persists trip (evidence: `app/services/trip_service.py`)
- Trip orchestration → SMS messaging: sends invitations (evidence: `app/services/trip_service.py`)
- SMS survey service → Survey engine: validates answers (evidence: `app/services/survey_service.py`)
- SMS survey service → Repositories: saves responses (evidence: `app/services/survey_service.py`)
- SMS survey service → SMS messaging: sends questions (evidence: `app/services/survey_service.py`)
- Web survey service → Repositories: saves responses
- SMS messaging → Twilio client: uses client (evidence: `app/services/sms_service.py`)
- Twilio client → Twilio SMS: sends SMS (evidence: `app/sms/twilio_client.py`)
- Recommendation routes → Recommendation orchestration: delegates to
- Recommendation orchestration → Repositories: loads trip and surveys (evidence: `app/services/recommendation_service.py`)
- Recommendation orchestration → Prompt renderer: renders prompt (evidence: `app/services/recommendation_service.py`)
- Recommendation orchestration → AI gateway: requests generation (evidence: `app/services/recommendation_service.py`)
- AI gateway → Ollama provider: dispatches to (evidence: `app/gateway/gateway.py`)
- Ollama provider → LLM service: sends inference request (evidence: `app/gateway/providers/ollama_provider.py`)
- Recommendation orchestration → Recommendation parser: parses response (evidence: `app/services/recommendation_service.py`)
- Recommendation orchestration → Repositories: replaces recommendations (evidence: `app/services/recommendation_service.py`)
- Vote routes → Voting orchestration: delegates to (evidence: `app/api/votes.py`)
- Voting orchestration → Repositories: reads and writes votes (evidence: `app/services/voting_service.py`)
- Voting orchestration → Ranked-choice algorithm: runs election (evidence: `app/services/voting_service.py`)
- Repositories → Database sessions: queries session
- Database sessions → PostgreSQL: connects to (evidence: `app/database.py`)
