bhavya-06darshnik/curiosity-button

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.