FinQuest MVP Release

1. Product Overview

TL;DR

FinQuest is an AI-powered financial education platform that helps beginner investors learn through personalized modules while tracking their portfolios. Users complete an onboarding quiz, add their stock positions, and receive AI-generated learning suggestions based on their goals and portfolio. The platform uses gamification (XP, levels, streaks, badges) to motivate consistent learning. All core features are dynamic, pulling real-time market data and generating personalized content.

Jobs To Be Done (JTBD)

1. As a beginner investor, I want to add my holdings and see real-time portfolio analytics, so that I can understand my overall performance and diversification.

2. As a beginner investor, I want to receive a learning pathway tailored to my goals and knowledge, so that I can learn finance concepts in a structured and relevant way.

3. As a learner, I want to test my understanding through quizzes, so that I can reinforce what I've learned and track progress.

4. As a beginner investor, I want AI to highlight learning modules based on my portfolio and goals, so that I can focus on knowledge that's most useful to my situation.

5. As a learner, I want to earn streaks and badges for completing modules, so that I stay motivated to return and continue learning consistently.

Core Customer User Journeys (CUJs)

CUJ 1: Portfolio Setup and Analytics

Description: From the dashboard or portfolio page, the user clicks a button and enters the ticker of a new position. They enter the quantity and average cost and click a button to add the position to their portfolio. The portfolio is updated with the new position and the user is redirected to the portfolio page where they can see their updated portfolio and view analytics about their portfolio based on real-time price data.

Implementation:

• Frontend: app/web/components/AddPositionDialog.tsx
• Backend: app/services/api/src/finquest_api/routers/portfolio.py - POST /api/portfolio/positions
• Service: app/services/api/src/finquest_api/services/portfolio.py - create_position_from_avg_cost()
• Data Source: Real-time prices via yfinance integration

Status: ✅ Fully Dynamic - Real-time market data, live portfolio calculations

CUJ 2: Personalized Learning Pathway

Description: When signing up, the user answers a short onboarding quiz about their financial goals and current knowledge (e.g., saving for retirement, risk tolerance, familiarity with investing terms). The AI generates a personalized pathway with beginner-friendly modules. The user sees their recommended first module and clicks on it to begin learning. The user reads the module and completes a series of multiple choice questions to test their understanding. At the end of the module, the user sees a congratulatory popup and is prompted to continue to the next module.

Implementation:

• Onboarding: app/web/pages/onboarding.tsx
• Learning Pathway: app/web/components/LearningPathway.tsx
• Module Viewer: app/web/components/ModuleViewer.tsx
• Backend Module Generation: app/services/api/src/finquest_api/services/module_generator.py
• Backend API: app/services/api/src/finquest_api/routers/modules.py

Status: ✅ Fully Dynamic - AI-generated modules based on user profile and portfolio

CUJ 3: Adaptive AI Learning Suggestions

Description: The user is able to view personalized suggestions on their dashboard about their portfolio based on their financial goals. These suggestions are generated by AI and the user can click "Start Module" to view the suggested AI generated module in the "Learning" page.

Implementation:

• Frontend Widget: app/web/components/SuggestionsWidget.tsx
• Backend Suggestion Generator: app/services/api/src/finquest_api/services/suggestion_generator.py
• Backend API: app/services/api/src/finquest_api/routers/users.py - GET /api/v1/users/suggestions
• AI Integration: app/services/api/src/finquest_api/services/llm/service.py

Status: ✅ Fully Dynamic - AI analyzes user profile and portfolio to generate personalized suggestions

CUJ 4: Gamification

Description: Every day that the user completes a learning module, a streak counter is incremented and the user sees a congratulatory message. The user can view their streak counter on the dashboard and in the "Profile" page.

Implementation:

• Gamification Context: app/web/contexts/GamificationContext.tsx
• Gamification Service: app/services/api/src/finquest_api/services/gamification.py
• Backend API: app/services/api/src/finquest_api/routers/gamification.py
• UI Components: app/web/components/XPBar.tsx, app/web/components/StreakIndicator.tsx

Status: ✅ Fully Dynamic - Real-time XP tracking, streak calculations, badge evaluation

---

2. MVP Development

Initial Hypothesis

Core Problem: Beginner investors lack accessible, personalized financial education that connects learning to their actual portfolio. Existing platforms either focus solely on portfolio tracking or offer generic educational content that doesn't adapt to individual needs.

Initial Product Idea: A financial education platform that combines portfolio tracking with AI-powered personalized learning modules. The platform would analyze a user's portfolio and financial goals to generate tailored educational content.

Key Assumptions:

1. Users want to learn about finance in the context of their actual investments
2. Gamification (XP, streaks, badges) will increase engagement and retention
3. AI can effectively generate personalized, relevant educational content
4. Real-time portfolio analytics are essential for user value
5. A single platform combining education and tracking is more valuable than separate tools

Initial Architecture Vision:

• Frontend: Next.js with React (ADR-001)
• Backend: FastAPI (ADR-002)
• Database: PostgreSQL with Prisma ORM (ADR-003) - Later pivoted
• Market Data: yfinance (ADR-004)
• Authentication: JWT/OAuth2 (ADR-005)
• AI: OpenAI API (ADR-006) - Later pivoted to Gemini
• Hosting: Vercel + Render + Supabase (ADR-007)

Key Learnings and Pivots

Pivot 1: Database and ORM (ADR-009)

Initial Decision (ADR-003): PostgreSQL with Prisma ORM for type-safe queries

Learning: Prisma is TypeScript-centered and doesn't have strong Python community libraries. Since our backend is Python-based (FastAPI), we needed a Python-native ORM.

Pivot: Switched to Supabase + SQLAlchemy

• Supabase provides built-in authentication, database, and storage
• SQLAlchemy is Python-native and integrates seamlessly with FastAPI
• This simplified our architecture by consolidating authentication and database into one platform

Impact: Reduced complexity, faster development, better Python ecosystem alignment

Source: architecture/adrs/adr-009.md

Pivot 2: AI Provider (ADR-006 → Implementation)

Initial Decision (ADR-006): OpenAI API for AI integration

Learning: During implementation, we evaluated multiple LLM providers. Gemini 2.0 Flash offered better cost-effectiveness and structured output capabilities for our use case.

Pivot: Implemented Google Gemini 2.0 Flash

• Better structured output support for generating modules and suggestions
• More cost-effective for our use case
• Provider-agnostic architecture allows future switching

Impact: Lower costs, better structured output, maintained flexibility

Implementation:

• app/services/api/src/finquest_api/services/llm/providers/gemini.py

Pivot 3: Frontend Component Library (ADR-010)

Initial Consideration: Multiple options including Tailwind CSS, Chakra UI, Material UI

Learning: Needed a React-based component library with comprehensive components and good design system. Mantine offered the best balance of features, ease of use, and extensibility.

Decision: Mantine UI

• Large set of components
• Good design sy...

Assignment 9: CUJ's 2 and 3

What's Changed

• Added model interface with tests in #58
• Add personalized learning suggestions and modules in #61

Full Changelog: v0.6.0...v0.7.0

Progress

Direct Links to Submitted Files

Backend API Files

• Modules Router

• Users Router

• LLM Service

• LLM Client Base

• LLM Factory

• LLM Models

• Gemini Provider

• OpenAI Provider

• LLM Utils

• LLM Dependencies

• Module Generator Service

• Suggestion Generator Service

• Schemas

• Main API

• API Configuration

• Environment Example

• API Dependencies

• LLM Service Example

• LLM Service Tests

• Gemini Provider Tests

Frontend Web Files

• Learn Page

• Module Detail Page

• Module Viewer Component

• Suggestions Widget Component

• Dashboard Page

• Portfolio Page

• Onboarding Page

• App Navigation Component

• API Client

• Learning Types

• User Types

• Web Dependencies

Roadmap Update

Our team has made significant progress on CUJ 2 and CUJ 3: AI-Powered Learning Modules and Personalized Suggestions. This release delivers a complete learning system that provides users with personalized educational content based on their portfolio composition and financial profile. We've built a robust LLM service abstraction layer supporting multiple providers (Gemini and OpenAI) with structured output capabilities, enabling reliable AI-generated content. The backend implements a comprehensive module generation system that creates educational content tailored to user needs, while the suggestion engine analyzes user portfolios and profiles to recommend relevant learning modules. The frontend provides an intuitive learning interface with interactive module viewers, quiz functionality, and a suggestions widget that displays personalized recommendations. Key technical achievements include implementing a provider-agnostic LLM service architecture, background task support for asynchronous suggestion generation, and a complete learning module system with versioned content and progress tracking. This milestone establishes the foundation for our AI-powered financial education platform and demonstrates our ability to integrate complex AI services with a modern web application.

Issues Summary

This release implements CUJ 2 and CUJ 3 functionality, building on the portfolio tracking foundation from CUJ 1. The implementation addresses the following areas:

• LLM Service Architecture: Created a provider-agnostic interface supporting multiple LLM providers with structured output support for reliable JSON responses

• Background Task Management: Resolved session management issues in background tasks for asynchronous suggestion generation

• Module System: Implemented a complete learning module system with versioned content, quiz questions, and progress tracking

• Suggestion Engine: Built AI-powered suggestion generation that analyzes user portfolios and profiles to recommend relevant learning content

Roadmap, Architecture, and Use Cases Changes

Architecture Changes

This release introduces a significant architectural enhancement with the LLM Service Layer. We've implemented a provider-agnostic architecture that abstracts LLM interactions, allowing us to support multiple providers (currently Gemini and OpenAI) while maintaining flexibility for future additions. This decision enables us to:

• Switch between LLM providers based on cost, performance, or feature requirements
• Support structured outputs for reliable JSON responses
• Implement comprehensive error handling and retry logic
• Maintain testability through dependency injection

The learning module system introduces several new architectural components:

• Module Generator Service: Generates educational content using LLM services, creating modules tailored to specific financial topics

• Suggestion Generator Service: Analyzes user data (portfolio, profile, progress) to generate personalized learning recommendations

• Background Task System: FastAPI background tasks enable asynchronous suggestion generation without blocking user requests

• Module Versioning: Content versioning system allows for module updates while preserving user progress

Database Schema Extensions

New models introduced in this release:

• Learning Modules: Module, ModuleVersion, ModuleQuestion, ModuleChoice - Complete learning content structure
• Progress Tracking: ModuleAttempt, ModuleAttemptAnswer, ModuleCompletion - User progress and quiz results
• AI Suggestions: Suggestion - Personalized learning recommendations with confidence scoring
• Onboarding: OnboardingResponse - Stores user financial profile data used for personalization

Use Cases

CUJ 2: Personalized Learning Suggestions - COMPLETED

Users now receive AI-generated learning suggestions based on:

• Portfolio composition and holdings
• Financial profile from onboarding
• Learning progress and completed modules
• Investment goals and experience level

CUJ 3: Interactive Learning Modules - COMPLETED

Users can now:

• Browse available learning modules
• View module content with markdown rendering
• Complete interactive quizzes with immediate feedback
• Track progress and module completions
• Access explanations for quiz questions

UI/UX

New Pages and Components:

1. Learn Page (/learn): A dedicated learning hub featuring:

   • Browse available learning modules
   • View personalized suggestions
   • Access module content and quizzes

2. Module Detail Page (/modules/[id]): Individual module view with:

   • Full module content (markdown)
   • Interactive quiz system
   • Question explanations
   • Progress tracking
   • Completion status

3. Module Viewer Component: Interactive component for displaying modules:

   • Markdown content rendering
   • Quiz question display with multiple choice answers
   • Immediate feedback on answer selection
   • Explanation display for each question
   • Progress indicator

4. Suggestions Widget Component: Displays personalized recommendations:

   • Suggestion cards with reason and confidence
   • Direct links to recommended modules
   • Status tracking (shown, clicked, dismissed, completed)
   • Integration with dashboard and portfolio pages

5. Enhanced Dashboard: Updated to include:

   • Suggestions widget integration
   • Quick access to learning modules

6. Enhanced Portfolio Page: Updated to include:

   • Suggestions widget for portfolio-based recommendations
   • Context-aware learning suggestions

Additional Technical Decisions:

1. Provider-Agnostic LLM Architecture: Chose to abstract LLM providers rather than hardcode to a single provider. This provides flexibility to switch providers or use multiple providers simultan...

Assignment 8

What's Changed

• CUJ 1: Investment portfolio tracking by @jasonfyw in #55

Full Changelog: 0.6.0...v0.6.0

Progress

Direct Links to Submitted Files

Backend API Files

• Portfolio Router
• Portfolio Service
• Snapshots Job
• Pricing Service
• FX Service
• Instruments Service
• Schemas
• Auth Utils
• Main API
• Database Models
• Database Session
• API Configuration
• Environment Example
• API Dependencies

Frontend Web Files

• Portfolio Page
• Dashboard Page
• Add Position Dialog Component
• Value Chart Component
• Allocation Chart Component
• App Navigation Component
• API Client
• Portfolio Types
• App Configuration
• Global Styles
• Web Environment Example
• Web Dependencies

Roadmap Update

Our team has made significant progress on CUJ 1: Investment Portfolio Tracking, successfully implementing the core portfolio management functionality. This release delivers a complete end-to-end portfolio tracking system that allows users to add positions, view their holdings, and analyze portfolio performance through interactive charts and analytics. We've built a robust backend API using FastAPI and SQLAlchemy that handles position management, pricing based on real data from Yahoo Finance, currency conversion, and historical portfolio valuation snapshots. The frontend implements the mockups and provides an intuitive interface with dark mode support and responsive charts. Key technical achievements include implementing a snapshot system for historical portfolio valuations and creating reusable chart components for portfolio visualization. This milestone establishes the foundation for our financial education platform and demonstrates our ability to integrate complex financial data with a modern web application.

Issues Summary

This release closes the following issues: #6 #7 #12 #16 #17 #18

In doing so, our team has addressed several technical challenges and improvements:

• Database Error Fixes: Resolved issues with portfolio snapshot generation and database query optimization
• Chart Loading Improvements: Enhanced chart components with proper loading states and skeleton screens to improve perceived performance

Roadmap, Architecture, and Use Cases Changes

Architecture Changes

We have formalized our database and ORM decision through ADR 009: Database, Authentication, and ORM – Supabase and SQLAlchemy. This decision establishes Supabase as our authentication and database platform, with SQLAlchemy as our Python-native ORM. This simplifies our architecture by leveraging Supabase's built-in authentication and database capabilities while maintaining flexibility with SQLAlchemy for complex queries and data modeling.

The portfolio tracking feature introduces several new architectural components:

• Portfolio Service Layer: Handles position computation using average cost method, portfolio analytics, and allocation calculations
• Snapshots System: Implements a time-series database pattern for storing historical portfolio valuations at different granularities (hourly, 6-hourly, daily, weekly)
• Historical Price Service: Integrates with yfinance to fetch historical prices for accurate portfolio valuation at any point in time
• FX Conversion Service: Handles multi-currency portfolios with historical and real-time foreign exchange rate conversion

Use Cases

No changes to use cases were made in this release. CUJ 1 remains as specified: users can add positions from the dashboard or portfolio page, enter ticker symbols with quantity and average cost, and view updated portfolio analytics with real-time price data.

Roadmap Change Details

Architecture

New Components Introduced:

1. Portfolio Valuation Snapshot System: A time-series storage system that captures portfolio valuations at regular intervals. This system supports multiple granularities (hourly, 6-hourly, daily, weekly) and automatically generates missing snapshots when requested. The implementation uses historical price data to calculate accurate portfolio values at any point in time.

2. Position Management Service: A service layer that computes positions from transactions using the average cost method. This handles buy/sell transactions, maintains average cost basis, and calculates unrealized P/L and daily P/L for each position.

3. Historical Price Integration: Integration with yfinance API to fetch historical prices for accurate portfolio valuation snapshots. The system falls back to latest prices when historical data is unavailable.

Database Schema Extensions:

• PortfolioValuationSnapshot model for storing time-series portfolio valuations
• Enhanced Transaction model with FX rate tracking
• Instrument model with currency and sector information

UI/UX

New Pages and Components:

1. Portfolio Page (/portfolio): A comprehensive portfolio view featuring:

   • Interactive portfolio value chart with time range selection (1D, 1W, 1M, YTD, 1Y)
   • Asset allocation pie chart showing distribution by instrument type
   • Summary cards displaying total value, total gain/loss, and daily change
   • Detailed holdings table with position-level analytics
   • Add position button with modal dialog

2. Dashboard Page (/dashboard): A simplified dashboard view showing:

   • Portfolio value chart with overlay displaying current value and daily percentage change
   • Clean, focused interface for quick portfolio overview

3. Add Position Dialog: A modal form for adding new positions with:

   • Ticker symbol input with validation
   • Quantity and average cost inputs
   • Optional execution date/time field
   • Inline error handling and loading states

4. Value Chart Component: A reusable chart component featuring:

   • Responsive line chart using Recharts
   • Time range selector (1D, 1W, 1M, YTD, 1Y)
   • Refresh button for manual snapshot generation
   • Optional overlay for displaying current value and percentage change
   • Dark mode support with theme-aware styling
   • Skeleton loading states for better perceived performance

5. Allocation Chart Component: A reusable pie chart component showing:

   • Asset allocation by type (equity, ETF, crypto)
   • Custom color scheme with legend
   • Responsive design

Additional Technical Decisions:

1. Average Cost Method for Position Tracking: Chose average cost method over FIFO/LIFO for its simplicity and beginner-friendliness. This method calculates the average purchase price of all shares, making it easier for users to understand their cost basis.

2. Snapshot-Based Historical Valuations: Decided to store discrete snapshots rather than recalculating on-demand. This approach provides faster query performance and allows for accurate historical analysis, though it requires more ...

Assignment 7 - Competitive CUJ

Full Changelog: v0.5.1...0.6.0

🚀 Overview of This Release

Progress

This week we identified a competitor tool that aims to achieve the same or a similar objective as your project and documented the process of using it along with its comparison with FinQuest. From this we decided on actionable insights and improvements.

➕ File Added:

• CSC491 A7 - Competitive CUJ.pdf

Assignment 6: CI and Testing

CI & Testing Foundations

Submitted files

• GitHub Actions
  • .github/workflows/api-ci.yml
  • .github/workflows/web-ci.yml
• Backend (FastAPI)
  • app/services/api/pyproject.toml
  • Tests & fixtures: app/services/api/tests/
    (e.g., conftest.py, test_auth_*.py, test_health_*.py)
• Frontend (Next.js)
  • Component test: app/web/src/test/components/ProtectedRoute.test.tsx
  • Test setup: app/web/src/test/setup.ts
  • Playwright config & e2e specs: app/web/e2e/ and app/web/playwright.config.ts

---

Progress:

This release establishes our end-to-end testing and continuous integration for both the API (FastAPI) and Web App (Next.js). We added unit/integration tests for the API’s auth and health endpoints using pytest and FastAPI’s TestClient, with Supabase calls safely mocked to avoid network/secret coupling. On the frontend, we added Vitest + React Testing Library coverage for ProtectedRoute, including loading state, redirect on unauthenticated access, and rendering on authenticated sessions, alongside a JSDOM test setup to mock browser APIs required by Mantine (matchMedia, ResizeObserver). We also added Playwright e2e smoke tests and an artifact upload step for the HTML report. Two GitHub Actions workflows now run on push/PR to master: API CI (ruff lint, pytest, import/startup smoke) and Web App CI (lint, typecheck, unit tests, e2e). CI injects required Supabase env vars via repository secrets. Collectively, this gives us a reproducible, automated signal for regressions, validates our auth flows at multiple layers, and unblocks future work like coverage gating and preview deployments.

---

Roadmap update

• Scope delivered in this assignment: green CI for API & Web; backend auth/health tests; ProtectedRoute unit tests; Playwright e2e smoke; cached, deterministic Node/Python installs (pnpm store cache; uv sync for Python); artifact upload for e2e reports.
• What this enables next: coverage thresholds and PR gating; adding API contract tests; expanding e2e to real CUJs; per-PR ephemeral previews.

---

Issue summaries (opened/closed since last release)

• [Closed] CI/CD Pipeline (Lint, Test, Typecheck) — Set up GitHub Actions to run linting, type-checking, and test suites on pull requests.
• [Closed] Authentication & Session Management — Implement secure user authentication and session management using NextAuth (email/password or OAuth). Required for all CUJs.

---

Architecture / UI-UX / Research (3+ components)

Architecture

• Split workflows: api-ci and web-ci to parallelize and isolate failures.
• Python uses uv for fast lockfile-driven installs; Node uses pnpm with cached store keyed by pnpm-lock.yaml.
• Secrets are injected only where needed (SUPABASE_URL/KEY/JWT_SECRET for API; NEXT_PUBLIC_* for Web), reducing blast radius.

Research & Decisions

• Testing libraries:
  • API: pytest + TestClient for speed and fixture ergonomics.
  • Web: Vitest + RTL to test behavior over implementation details.
  • E2E: Playwright chosen for reliability and auto-installable browsers in CI.
• Key challenges & resolutions:
  • Supabase client initialization during tests → patched before import to avoid side effects.
  • Mantine requires browser APIs not present in JSDOM → mocked matchMedia and ResizeObserver in test setup.

Decisions log

• Standardized on Node 20 and Python 3.11 in CI for consistency with local dev.
• Added a lightweight API import/startup smoke step to catch import/config errors early (faster failure than full test run).
• Uploaded Playwright HTML report as an artifact to simplify debugging flaky e2e runs.

Milestone update

• ✅ CI green on push/PR to master for API & Web
• ✅ Unit/Integration tests for auth & health (API) and ProtectedRoute (Web)
• ✅ E2E smoke running and report uploaded
• ⏳ Add coverage gates & PR status checks
• ⏳ Expand e2e to cover core CUJs (auth + protected flows)

---

JTBD (testing angle)

• When pushing code, we want fast, reliable CI signals so we can merge confidently without breaking auth flows or protected routes.
• When changing auth or routing, we want unit tests + e2e smoke that fail loudly if redirects, loading, or rendering regress.

---

How to run tests locally

API

cd app/services/api
uv sync --extra dev
uv run pytest -v

Web

cd app/web
pnpm install --frozen-lockfile
pnpm test:run        # unit tests
pnpm test:coverage   # coverage
pnpm build && pnpm test:e2e  # e2e (Playwright)

Ensure local env vars mirror CI:
API → SUPABASE_URL, SUPABASE_KEY, SUPABASE_JWT_SECRET
Web → NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY

Assignment 5 – Decisions and Tech Stack

🚀 Overview of This Release

Progress

This release marks a beginning in the development of FinQuest - transitioning from planning to actual implementation. We've built the foundational codebase for both the frontend web application and the backend API service, establishing the core infrastructure that will power FinQuest's web app

Building on the architecture decisions and planning completed in the previous release, we have:

• Implemented a modern Next.js web application with authentication and basic pages
• Built a FastAPI backend service with Supabase integration
• Established the development environment and tooling for both frontend and backend

---

➕ Added

📂 Architecture Decision Records (ADRs)

• ADR-009: Database, Authentication, and ORM – Supabase and SQLAlchemy
  • Selected Supabase for database and authentication
  • Chose SQLAlchemy as Python-native ORM
  • Provides built-in authentication, storage, and real-time capabilities
• ADR-010: Frontend Component Library – Mantine
  • Selected Mantine as the React component library
  • Provides comprehensive UI components with excellent design system
  • Includes plugins for extended functionality

🌐 Frontend Web Application app/web

Tech Stack: Next.js 15, React 19, TypeScript, Mantine UI, Supabase

Core Pages

• Landing Page (pages/index.tsx)
  • Modern hero section with gradient background
  • Call-to-action buttons for signup/login
  • Responsive navigation header with logo
  • Dark/light mode toggle support
• Authentication Pages (pages/login.tsx & pages/signup.tsx)
  • pages/login.tsx - User login with email/password and Google OAuth
  • pages/signup.tsx - New user registration
  • pages/onboarding.tsx - Post-signup onboarding flow

Components

• components/GradientBackground.tsx - Animated gradient background component
• components/ProtectedRoute.tsx - Route protection wrapper for authenticated pages

Authentication & State Management

• contexts/AuthContext.tsx - Comprehensive authentication context with:
  • User session management
  • Sign up, sign in, sign out functions
  • Google OAuth integration
  • Protected route handling
• lib/supabase.ts - Supabase client configuration

🔧 Backend API Service (app/services/api/)

Tech Stack: FastAPI, Python 3.9+, Supabase, SQLAlchemy, uv package manager

Core Application

• src/finquest_api/main.py - FastAPI application with:
  • CORS middleware configuration
  • Router registration
  • Swagger/ReDoc API documentation
  • Version 0.1.0
• src/finquest_api/config.py - Application settings and configuration
• src/finquest_api/schemas.py - Pydantic models for request/response validation
• src/finquest_api/auth_utils.py - Authentication utility functions
• src/finquest_api/supabase_client.py - Supabase client configuration

API Routers

• routers/health.py - Health check and readiness endpoints
• routers/api.py - Main API v1 endpoints
• routers/auth.py - Authentication endpoints

---

🏗️ Project Structure

app/
├── web/                    # Next.js frontend application
│   ├── pages/             # Page routes
│   ├── components/        # Reusable React components
│   ├── contexts/          # React contexts (Auth, etc.)
│   ├── lib/               # Utility libraries
│   ├── assets/            # Images and static assets
│   └── public/            # Public assets
└── services/
    └── api/               # FastAPI backend service
        └── src/
            └── finquest_api/
                ├── routers/      # API route handlers
                ├── main.py       # FastAPI app
                ├── config.py     # Settings
                ├── schemas.py    # Data models
                └── auth_utils.py # Auth utilities

---

🔄 Architecture Integration

This release implements the following architecture decisions:

• ✅ Next.js + React frontend (ADR-002)
• ✅ FastAPI backend (ADR-003)
• ✅ TypeScript for type safety (ADR-004)
• ✅ RESTful API architecture (ADR-005)
• ✅ Supabase for database and auth (ADR-009)
• ✅ Mantine UI component library (ADR-010)

---

🐛 Issue Summary

No major issues in this release. The codebase compiles and runs successfully with all core features functional.

Known Limitations

• Onboarding flow is scaffolded but not fully implemented
• Portfolio management features are pending implementation
• Market data integration is planned for next release
• Testing suite needs to be added

A4 fixed

🚀 Overview of This Release

Progress

This week we planned out the main use cases of our application and scoped down the work we aim to achieve. The architecture diagram, stack choices, and intial issues were completed as part of this work.

• Planned out short term, medium term, and long term goals:

  • Short term (~ Oct. 31st, 2025): See all issues and their subtasks under https://github.com/dcsil/Code418/milestone/1
  • Medium term (December 31, 2025): See all issues and their subtasks under https://github.com/dcsil/Code418/milestone/2
  • Long term (Beyond the course): See all issues and their subtasks under https://github.com/dcsil/Code418/milestone/3

➕ Added

• 📂 Architecture ADRs

  • ADR-001
  • ADR-002
  • ADR-003
  • ADR-004
  • ADR-005
  • ADR-006
  • ADR-007
  • ADR-008

• 🖼️ Architecture Diagram

  • diagram.md
  • diagram.png

• 📊 Product Research

  • market.md
  • roadmap.md
  • use_cases.md

Issue Summary

No major issue in this release.

A4 - Initial Project Roadmap Product Definition Milestone breakdown Code release pipeline

🚀 Overview of This Release

Progress

This week we planned out the main use cases of our application and scoped down the work we aim to achieve. The architecture diagram, stack choices, and intial issues were completed as part of this work.

• Planned out short term, medium term, and long term goals:

  • Short term (~ Oct. 31st, 2025): see this epic and sub-tasks along with https://github.com/orgs/dcsil/projects/100/views/1?pane=issue&itemId=131714753&issue=dcsil%7CCode418%7C20, https://github.com/orgs/dcsil/projects/100/views/1?pane=issue&itemId=131714959&issue=dcsil%7CCode418%7C21, and https://github.com/orgs/dcsil/projects/100/views/1?pane=issue&itemId=131715046&issue=dcsil%7CCode418%7C22
  • Medium term (Nov. 1st, 2025 ~ Mar. 31st, 2026): this epic and sub-tasks
  • Long term (Apr. 2026 and beyond): See #18 and subtasks
    ➕ Added

• 📂 Architecture ADRs

  • ADR-001
  • ADR-002
  • ADR-003
  • ADR-004
  • ADR-005
  • ADR-006
  • ADR-007
  • ADR-008

• 🖼️ Architecture Diagram

  • diagram.md
  • diagram.png

• 📊 Product Research

  • market.md
  • roadmap.md
  • use_cases.md

Issue Summary

No major issue in this release.

Assignment 3 - CUJ Runthrough + Demo

🚀 Overview of This Release

• ➕ Added
  • 📄 CUJ Document
  • 🌐 End Product
    • Code for Landing Page
    • Link to Landing Page

Progress

This week we built a working prototype of the code418 web console with a holdings dashboard, news tab, and task list. This helped us note where our assumptions aligned with user needs and where they were off.

We then focused on documenting and analyzing the CUJ of the process of creating the prototype. This helped us understand how we can improve our dev setup, improve existing tooling, and also at a more meta level helped us get more familiar with creating and analyzing CUJs.

Issue Summary

No major issue in this release.

Changes to roadmap, architecture, or use cases

No changes in this release.

Assignment 2 - Team Exploration - Bias and Diversity Reflection

🚀 Overview of This Release

• 📝 Added
  • 👥 Diversity Page
  • 🔗 Add reference to Diversity Page in team ReadMe

Progress

This week we reflected on strengths and weaknesses of our team, explore our unconscious bias, and evaluated the general diversity of the team. Further, we identified where we need to bring in subject matter experts and where we could improve our team’s diversity.

Issue Summary

No major issue in this release.

Changes to roadmap, architecture, or use cases

No changes in this release.