# bhavya-06darshnik/curiosity-button architecture

> Architecture diagram of the GitHub repository bhavya-06darshnik/curiosity-button, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/bhavya-06darshnik/curiosity-button
- Repository: https://github.com/bhavya-06darshnik/curiosity-button

## Overview

#### Purpose and Entry Points
Curio is a split frontend/backend application for discovering and presenting topics, with backend services that combine topic logic, Wikipedia retrieval, and LLM-backed generation. The backend is a Django project rooted at `curio/manage.py`; the frontend is a Vite/React client rooted at `frontend/src/main.jsx`.

#### Backend Application and HTTP Boundary
Django configuration and deployment entry points are in `curio/curio/settings.py`, `curio/curio/urls.py`, `curio/curio/asgi.py`, and `curio/curio/wsgi.py`. The project-level router delegates API traffic to the `api` Django app through `curio/api/urls.py`. Request handlers reside in `curio/api/views.py`, forming the primary boundary between browser requests and server-side topic-generation workflows.

#### API Domain Layer
The `api` app owns server domain concerns: persistence models in `curio/api/models.py`, API-wide constants in `curio/api/constants.py`, and Django admin registration in `curio/api/admin.py`. Database migrations are expected under `curio/api/migrations`; the checked-in development database is `curio/db.sqlite3`. This layer should remain the source of truth for durable topic-related records rather than frontend state.

#### Topic Enrichment Pipeline
Topic-oriented orchestration is concentrated in `curio/api/services/topic.py`. It is supported by two external-information boundaries:
- `curio/api/services/wikipedia.py` retrieves or normalizes Wikipedia-derived content.
- `curio/api/services/llm.py` invokes an LLM capability for generated or transformed topic material.

The expected control flow is HTTP view → topic service → Wikipedia and/or LLM service → response serialization. These integrations are architecturally important because network behavior, credentials, response quality, and failure handling are isolated from views and models.

#### React Discovery Client
The React application bootstraps in `frontend/src/main.jsx` and composes its primary UI in `frontend/src/App.jsx`. Discovery-oriented presentation is split into `frontend/src/components/Hero.jsx`, `frontend/src/components/DiscoverOrb.jsx`, and `frontend/src/components/TopicCard.jsx`; shared visual behavior includes `frontend/src/components/Background.jsx` and `frontend/src/components/LoadingText.jsx`. Theme definitions are centralized in `frontend/src/themes.js`.

#### Client Data Flow
`frontend/src/hooks/useTopic.js` is the client-side topic state/control boundary. It should mediate loading, error, and result state between UI components and the backend. `frontend/src/services/api.js` is the transport boundary for requests to Django, preventing components from coupling directly to API URLs or request mechanics. The main browser flow is user discovery interaction → `useTopic` → API service → Django API → topic enrichment pipeline → topic state → cards/loading UI.

#### Runtimes and Dependencies
Backend runtime metadata is represented by `pyproject.toml`, `requirements.txt`, and `uv.lock`, with Python version selection in `.python-version`. The frontend uses Node package metadata in `frontend/package.json` and Vite configuration in `frontend/vite.config.js`. Django supports both ASGI and WSGI deployment paths; the frontend is a separately built static client. External service dependencies are implied by the LLM and Wikipedia service modules, while SQLite is the local persistence implementation present in the repository.

Main entry points: [`curio/api/services/topic.py`](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/topic.py) (Topic service), [`frontend/src/hooks/useTopic.js`](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/hooks/useTopic.js) (Topic state hook), [`frontend/src/App.jsx`](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/App.jsx) (App shell), [`frontend/src/services/api.js`](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/services/api.js) (API transport)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Client"]
  node_react_entry["React entry<br/>bootstrap<br/>[main.jsx]"]
  node_app["App shell<br/>React composition<br/>[App.jsx]"]
  node_discovery_ui["Discovery UI<br/>React components<br/>[DiscoverOrb.jsx]"]
  node_feedback_ui["Loading visuals<br/>React components<br/>[LoadingText.jsx]"]
  node_theme["Theme definitions<br/>UI theme<br/>[themes.js]"]
  node_topic_hook["Topic state hook<br/>client state boundary<br/>[useTopic.js]"]
  node_api_client["API transport<br/>client service<br/>[api.js]"]
end

subgraph group_backend["Django Backend"]
  node_django_router["Django URL router<br/>HTTP routing<br/>[urls.py]"]
  node_api_urls["API routes<br/>app routing<br/>[urls.py]"]
  node_api_views["API views<br/>request handlers<br/>[views.py]"]
  node_topic_service["Topic service<br/>orchestration<br/>[topic.py]"]
  node_models["Topic models<br/>domain persistence<br/>[models.py]"]
  node_sqlite[("SQLite database<br/>local database<br/>[db.sqlite3]")]
end

subgraph group_external["External Boundaries"]
  node_wikipedia_service{{"Wikipedia service<br/>external-content adapter<br/>[wikipedia.py]"}}
  node_llm_service{{"LLM service<br/>generation adapter<br/>[llm.py]"}}
  node_wikipedia(("Wikipedia<br/>external content source"))
  node_llm(("LLM capability<br/>external AI service"))
end

node_react_entry -->|"mounts"| node_app
node_app -->|"composes"| node_discovery_ui
node_app -->|"shows state"| node_feedback_ui
node_app -->|"uses"| node_theme
node_discovery_ui -->|"starts discovery"| node_topic_hook
node_topic_hook -->|"requests topics"| node_api_client
node_api_client -->|"HTTP API request"| node_django_router
node_django_router -->|"delegates API traffic"| node_api_urls
node_api_urls -->|"routes"| node_api_views
node_api_views -->|"orchestrates"| node_topic_service
node_topic_service -->|"reads or persists"| node_models
node_models -->|"stores records"| node_sqlite
node_topic_service -->|"retrieves content"| node_wikipedia_service
node_topic_service -->|"generates material"| node_llm_service
node_wikipedia_service -->|"fetches"| node_wikipedia
node_llm_service -->|"invokes"| node_llm
node_topic_service -->|"topic result"| node_api_views
node_api_client -->|"response"| node_topic_hook
node_topic_hook -->|"topic state"| node_discovery_ui
node_topic_hook -->|"loading state"| node_feedback_ui

click node_react_entry "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/main.jsx"
click node_app "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/App.jsx"
click node_discovery_ui "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/components/DiscoverOrb.jsx"
click node_feedback_ui "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/components/LoadingText.jsx"
click node_theme "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/themes.js"
click node_topic_hook "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/hooks/useTopic.js"
click node_api_client "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/services/api.js"
click node_django_router "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/curio/urls.py"
click node_api_urls "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/urls.py"
click node_api_views "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/views.py"
click node_topic_service "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/topic.py"
click node_models "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/models.py"
click node_sqlite "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/db.sqlite3"
click node_wikipedia_service "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/wikipedia.py"
click node_llm_service "https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/llm.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_react_entry,node_app,node_discovery_ui,node_feedback_ui,node_theme,node_topic_hook,node_api_client toneBlue
class node_django_router,node_api_urls,node_api_views,node_topic_service,node_models,node_sqlite toneAmber
class node_wikipedia_service,node_llm_service,node_wikipedia,node_llm toneMint
```

## Components

### React Client

Vite-built browser application.

- [React entry](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/main.jsx): bootstrap · `frontend/src/main.jsx`
- [App shell](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/App.jsx): React composition · `frontend/src/App.jsx`
- [Discovery UI](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/components/DiscoverOrb.jsx): React components · Hero, discovery orb, and topic cards. · `frontend/src/components/DiscoverOrb.jsx`
- [Loading visuals](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/components/LoadingText.jsx): React components · `frontend/src/components/LoadingText.jsx`
- [Theme definitions](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/themes.js): UI theme · `frontend/src/themes.js`
- [Topic state hook](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/hooks/useTopic.js): client state boundary · Owns loading, error, and result state. · `frontend/src/hooks/useTopic.js`
- [API transport](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/frontend/src/services/api.js): client service · `frontend/src/services/api.js`

### Django Backend

API and topic-enrichment runtime.

- [Django URL router](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/curio/urls.py): HTTP routing · `curio/curio/urls.py`
- [API routes](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/urls.py): app routing · `curio/api/urls.py`
- [API views](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/views.py): request handlers · HTTP boundary for topic workflows. · `curio/api/views.py`
- [Topic service](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/topic.py): orchestration · Coordinates topic enrichment and response material. · `curio/api/services/topic.py`
- [Topic models](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/models.py): domain persistence · Source of truth for durable topic records. · `curio/api/models.py`
- [SQLite database](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/db.sqlite3): local database · `curio/db.sqlite3`

### External Boundaries

- [Wikipedia service](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/wikipedia.py): external-content adapter · `curio/api/services/wikipedia.py`
- [LLM service](https://github.com/bhavya-06darshnik/curiosity-button/blob/main/curio/api/services/llm.py): generation adapter · `curio/api/services/llm.py`
- **Wikipedia**: external content source
- **LLM capability**: external AI service

## Connections

- React entry → App shell: mounts
- App shell → Discovery UI: composes
- App shell → Loading visuals: shows state
- App shell → Theme definitions: uses
- Discovery UI → Topic state hook: starts discovery
- Topic state hook → API transport: requests topics
- API transport → Django URL router: HTTP API request
- Django URL router → API routes: delegates API traffic
- API routes → API views: routes
- API views → Topic service: orchestrates
- Topic service → Topic models: reads or persists
- Topic models → SQLite database: stores records
- Topic service → Wikipedia service: retrieves content
- Topic service → LLM service: generates material
- Wikipedia service → Wikipedia: fetches
- LLM service → LLM capability: invokes
- Topic service → API views: topic result
- API transport → Topic state hook: response
- Topic state hook → Discovery UI: topic state
- Topic state hook → Loading visuals: loading state