How threengineering/mainproject works
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: Widgets.jsx Widget router · main.py API app · App.jsx Dashboard page · TodoWidget.jsx Todo widget
Components 17
Frontend
React/Vite single-page dashboard and widget UI
- App shell · Bootstraps and mounts the client-side dashboard
src/main.jsx - Dashboard page · Composes the overall morning dashboard view
src/App.jsx - Widget router · Chooses and renders the active widget by state or config
src/components/widgets/Widgets.jsx - News widget · Renders news content in the dashboard
src/components/widgets/NewsWidget.jsx - Stock widget · Renders market data in the dashboard
src/components/widgets/StockWidget.jsx - Weather widget · Renders weather data in the dashboard
src/components/widgets/WeatherWidget.jsx - Todo widget · Renders user to-do content and actions
src/components/widgets/TodoWidget.jsx - Default widget · Fallback view when no specific widget matches
src/components/widgets/DefaultWidget.jsx - Icons · Shared icon set used by widgets
src/components/widgets/Icons.jsx - Login · Handles user sign-in entry points
src/components/Login.jsx - Supabase client · Frontend integration for session and user data access
src/supabaseClient.js
Backend
FastAPI domain APIs for dashboard data
- API app · Wires domain routes into the backend application
main.py - News API · Fetches and normalizes news data
api/news.py - Stock API · Fetches and normalizes market data
api/stock.py - Weather API · Fetches and normalizes weather data
api/weather.py
External Services
Third-party providers and auth/data platforms
- Supabase · Authentication boundary and likely user-specific persistence
- Data providers · Third-party news, market, and weather services
Connections 21
- 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