# threengineering/mainproject architecture

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

- Interactive diagram: https://gitdiagram.com/threengineering/mainproject
- Repository: https://github.com/threengineering/mainproject

## Overview

1. **System shape**
   - This repo is a two-tier dashboard application: a **React/Vite frontend** for the widget UI and a **Python FastAPI backend** for data access and aggregation.
   - The product goal is a single “morning dashboard” that combines **news, weather, stocks, and to-do items** into one view.

2. **Frontend boundary**
   - The frontend lives under `src/` and is built as a **single-page app**.
   - `src/main.jsx` bootstraps the app, `src/App.jsx` composes the page, and `src/App.css` / `src/index.css` provide styling.
   - `vite.config.js`, `tailwind.config.cjs`, and `postcss.config.js` show the UI is built with **Vite + Tailwind CSS**.

3. **Widget-based UI composition**
   - The UI is organized around reusable widget components in `src/components/widgets/`.
   - There are dedicated widgets for **News**, **Stock**, **Weather**, **Todo**, plus a `DefaultWidget` and shared `Icons`.
   - `src/components/widgets/Widgets.jsx` likely acts as the selector/renderer that chooses which widget to show based on state or configuration.

4. **Authentication and user session layer**
   - `src/components/Login.jsx` and `src/supabaseClient.js` indicate the frontend has a **login/auth flow** wired through **Supabase**.
   - In the architecture, Supabase is the likely boundary for **identity/session management** and possibly user profile or to-do persistence.
   - This supports the README’s goal of **Google OAuth-based login** and personalized dashboard behavior.

5. **Backend API layer**
   - The backend code is under `api/`, with separate modules for `news.py`, `stock.py`, and `weather.py`.
   - This suggests a **domain-split API design**, where each module owns one external data domain instead of a single monolithic handler.
   - `main.py` is the probable backend entrypoint that wires those routes into the FastAPI application.

6. **External data acquisition**
   - `api/news.py`, `api/stock.py`, and `api/weather.py` likely call third-party provider APIs and transform the responses before returning them to the frontend.
   - These modules represent the main integration boundary with **external news/weather/market services**.
   - The architecture therefore depends on provider APIs for freshness and coverage rather than storing those datasets locally.

7. **Data flow for dashboard rendering**
   - The browser loads the React app, the app authenticates the user, and then the widget components request domain data from the backend.
   - The backend fetches or normalizes the requested data and returns it to the widget layer for rendering.
   - For personalized features, the authenticated identity likely gates access to user-specific settings or to-do data.

8. **To-do and personalization path**
   - The README says the scope includes **user-specific To-Do CRUD** and personalized settings.
   - In the current tree, there is a `TodoWidget` on the frontend, but no visible `api/todo.py`; that suggests the persistence layer is either planned, hidden, or delegated through Supabase.
   - For an architecture diagram, treat to-do management as a separate data path from the read-only market/weather/news widgets.

9. **Configuration and secrets**
   - `.env` is present, so the app likely relies on environment-based configuration for API keys, backend URLs, and auth settings.
   - `requirements.txt` defines the Python backend dependencies, while `package.json` and `package-lock.json` define the frontend toolchain and JS dependencies.
   - This separation is important: frontend build/runtime dependencies are isolated from backend runtime dependencies.

10. **Static assets and app shell**
   - `public/` and `src/assets/` provide the static resources used by the dashboard.
   - `index.html` is the frontend shell served by Vite during development and bundled for production.
   - The app is therefore not server-rendered; it is a client-rendered dashboard with API-backed data hydration.

11. **Operational and deployment intent**
   - The README describes planned use of **Docker, GitHub Actions, and Oracle Cloud** for deployment/CI/CD.
   - Those pieces are part of the project’s intended runtime architecture, but they are not represented by dedicated repo folders here.
   - If diagramming the system, show them as deployment/infrastructure concerns around the app rather than as in-repo application components.

12. **Practical architectural summary**
   - Think of the system as: **React widget dashboard** → **FastAPI domain APIs** → **external information providers**, with **Supabase** handling authentication and likely user data.
   - The key structural boundary is between the **presentation layer** in `src/` and the **domain/integration layer** in `api/`.
   - The main design pattern is a **modular, widget-driven frontend consuming domain-specific backend endpoints**.

Main entry points: [`src/components/widgets/Widgets.jsx`](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/Widgets.jsx) (Widget router), [`main.py`](https://github.com/threengineering/mainproject/blob/main/main.py) (API app), [`src/App.jsx`](https://github.com/threengineering/mainproject/blob/main/src/App.jsx) (Dashboard page), [`src/components/widgets/TodoWidget.jsx`](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/TodoWidget.jsx) (Todo widget)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App shell<br/>Vite SPA entry<br/>[main.jsx]"]
  node_app_layout["Dashboard page<br/>React composition<br/>[App.jsx]"]
  node_widget_router["Widget router<br/>UI selector<br/>[Widgets.jsx]"]
  node_news_widget["News widget<br/>[NewsWidget.jsx]"]
  node_stock_widget["Stock widget<br/>[StockWidget.jsx]"]
  node_weather_widget["Weather widget<br/>[WeatherWidget.jsx]"]
  node_todo_widget["Todo widget<br/>[TodoWidget.jsx]"]
  node_default_widget["Default widget<br/>fallback widget<br/>[DefaultWidget.jsx]"]
  node_widget_icons["Icons<br/>shared UI<br/>[Icons.jsx]"]
  node_login_ui["Login<br/>auth UI<br/>[Login.jsx]"]
  node_supabase_client["Supabase client<br/>auth/data client<br/>[supabaseClient.js]"]
end

subgraph group_backend["Backend"]
  node_fastapi_main["API app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_news_api["News API<br/>domain route<br/>[news.py]"]
  node_stock_api["Stock API<br/>domain route<br/>[stock.py]"]
  node_weather_api["Weather API<br/>domain route<br/>[weather.py]"]
end

subgraph group_external["External Services"]
  node_supabase[("Supabase<br/>identity/storage platform")]
  node_provider_apis[("Data providers<br/>external APIs")]
end

node_app_shell -->|"mounts"| node_app_layout
node_app_layout -->|"auth flow"| node_login_ui
node_app_layout -->|"renders"| node_widget_router
node_widget_router -->|"selects"| node_news_widget
node_widget_router -->|"selects"| node_stock_widget
node_widget_router -->|"selects"| node_weather_widget
node_widget_router -->|"selects"| node_todo_widget
node_widget_router -->|"fallback"| node_default_widget
node_news_widget -->|"fetches via API"| node_fastapi_main
node_stock_widget -->|"fetches via API"| node_fastapi_main
node_weather_widget -->|"fetches via API"| node_fastapi_main
node_todo_widget -->|"uses client"| node_supabase_client
node_login_ui -->|"signs in"| node_supabase_client
node_supabase_client -->|"auth/session"| node_supabase
node_fastapi_main -->|"routes"| node_news_api
node_fastapi_main -->|"routes"| node_stock_api
node_fastapi_main -->|"routes"| node_weather_api
node_news_api -->|"queries"| node_provider_apis
node_stock_api -->|"queries"| node_provider_apis
node_weather_api -->|"queries"| node_provider_apis
node_todo_widget -.->|"reads/writes"| node_supabase

click node_app_shell "https://github.com/threengineering/mainproject/blob/main/src/main.jsx"
click node_app_layout "https://github.com/threengineering/mainproject/blob/main/src/App.jsx"
click node_widget_router "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/Widgets.jsx"
click node_news_widget "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/NewsWidget.jsx"
click node_stock_widget "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/StockWidget.jsx"
click node_weather_widget "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/WeatherWidget.jsx"
click node_todo_widget "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/TodoWidget.jsx"
click node_default_widget "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/DefaultWidget.jsx"
click node_widget_icons "https://github.com/threengineering/mainproject/blob/main/src/components/widgets/Icons.jsx"
click node_login_ui "https://github.com/threengineering/mainproject/blob/main/src/components/Login.jsx"
click node_supabase_client "https://github.com/threengineering/mainproject/blob/main/src/supabaseClient.js"
click node_fastapi_main "https://github.com/threengineering/mainproject/blob/main/main.py"
click node_news_api "https://github.com/threengineering/mainproject/blob/main/api/news.py"
click node_stock_api "https://github.com/threengineering/mainproject/blob/main/api/stock.py"
click node_weather_api "https://github.com/threengineering/mainproject/blob/main/api/weather.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_app_shell,node_app_layout,node_widget_router,node_news_widget,node_stock_widget,node_weather_widget,node_todo_widget,node_default_widget,node_widget_icons,node_login_ui,node_supabase_client toneBlue
class node_fastapi_main,node_news_api,node_stock_api,node_weather_api toneAmber
class node_supabase,node_provider_apis toneMint
```

## Components

### Frontend

React/Vite single-page dashboard and widget UI

- [App shell](https://github.com/threengineering/mainproject/blob/main/src/main.jsx): Vite SPA entry · Bootstraps and mounts the client-side dashboard · `src/main.jsx`
- [Dashboard page](https://github.com/threengineering/mainproject/blob/main/src/App.jsx): React composition · Composes the overall morning dashboard view · `src/App.jsx`
- [Widget router](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/Widgets.jsx): UI selector · Chooses and renders the active widget by state or config · `src/components/widgets/Widgets.jsx`
- [News widget](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/NewsWidget.jsx): widget · Renders news content in the dashboard · `src/components/widgets/NewsWidget.jsx`
- [Stock widget](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/StockWidget.jsx): widget · Renders market data in the dashboard · `src/components/widgets/StockWidget.jsx`
- [Weather widget](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/WeatherWidget.jsx): widget · Renders weather data in the dashboard · `src/components/widgets/WeatherWidget.jsx`
- [Todo widget](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/TodoWidget.jsx): widget · Renders user to-do content and actions · `src/components/widgets/TodoWidget.jsx`
- [Default widget](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/DefaultWidget.jsx): fallback widget · Fallback view when no specific widget matches · `src/components/widgets/DefaultWidget.jsx`
- [Icons](https://github.com/threengineering/mainproject/blob/main/src/components/widgets/Icons.jsx): shared UI · Shared icon set used by widgets · `src/components/widgets/Icons.jsx`
- [Login](https://github.com/threengineering/mainproject/blob/main/src/components/Login.jsx): auth UI · Handles user sign-in entry points · `src/components/Login.jsx`
- [Supabase client](https://github.com/threengineering/mainproject/blob/main/src/supabaseClient.js): auth/data client · Frontend integration for session and user data access · `src/supabaseClient.js`

### Backend

FastAPI domain APIs for dashboard data

- [API app](https://github.com/threengineering/mainproject/blob/main/main.py): FastAPI entrypoint · Wires domain routes into the backend application · `main.py`
- [News API](https://github.com/threengineering/mainproject/blob/main/api/news.py): domain route · Fetches and normalizes news data · `api/news.py`
- [Stock API](https://github.com/threengineering/mainproject/blob/main/api/stock.py): domain route · Fetches and normalizes market data · `api/stock.py`
- [Weather API](https://github.com/threengineering/mainproject/blob/main/api/weather.py): domain route · Fetches and normalizes weather data · `api/weather.py`

### External Services

Third-party providers and auth/data platforms

- **Supabase**: identity/storage platform · Authentication boundary and likely user-specific persistence
- **Data providers**: external APIs · Third-party news, market, and weather services

## Connections

- App shell → Dashboard page: mounts · Bootstraps the dashboard app
- Dashboard page → Login: auth flow · Shows sign-in before personalized content
- Dashboard page → Widget router: renders · Delegates dashboard sections to widget selection
- Widget router → News widget: selects · Routes news content to the news widget
- Widget router → Stock widget: selects · Routes market content to the stock widget
- Widget router → Weather widget: selects · Routes weather content to the weather widget
- Widget router → Todo widget: selects · Routes to-do content to the todo widget
- Widget router → Default widget: fallback · Uses a default widget when no match exists
- News widget → API app: fetches via API · Requests dashboard data from the backend
- Stock widget → API app: fetches via API · Requests dashboard data from the backend
- Weather widget → API app: fetches via API · Requests dashboard data from the backend
- Todo widget → Supabase client: uses client · Uses the auth/data client for user-specific operations
- Login → Supabase client: signs in · Initiates authentication through the Supabase client
- Supabase client → Supabase: auth/session · Connects the frontend to the identity platform
- API app → News API: routes · Registers the news domain module
- API app → Stock API: routes · Registers the stock domain module
- API app → Weather API: routes · Registers the weather domain module
- News API → Data providers: queries · Pulls data from external news sources
- Stock API → Data providers: queries · Pulls data from external market sources
- Weather API → Data providers: queries · Pulls data from external weather sources
- Todo widget → Supabase: reads/writes · User-specific to-do persistence likely goes through Supabase
