Skip to content

Igniters - Week 3 - Alex financial planner single agent on GCP #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
SectumPsempra wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Igniters - Week 3 - Alex financial planner single agent on GCP #142

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions community_contributions/a3_igniters_amitb/week3_final_exercise.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# Week 3 Final Exercise - Alex: AI Financial Planner

**Repository:** https://github.com/SectumPsempra/production/tree/week3-exercise-local/alex_financial_planner
**Deployed App:** https://alex-frontend-ajg5nndceq-uc.a.run.app

---

## What is Being Built

Alex is a cloud-native AI financial planning assistant. Users sign in, register their investment accounts and holdings, and ask Alex to analyse their portfolio. Alex responds with a written report, retirement projection, and allocation charts - all generated by an LLM through OpenRouter.

For Week 3, a **single-agent architecture** is sufficient. One agent - the Portfolio Analyst - receives the user's portfolio data (accounts, positions, asset class targets, years to retirement), calls an LLM via the OpenRouter API, and returns a structured JSON response containing the analysis report, chart data, and a retirement income estimate. The agent runs as a background job so the frontend can poll for results without blocking on a long LLM call.

---

## Architecture and Services

| Layer | GCP Service Used | AWS Equivalent |
|---|---|---|
| Frontend (Next.js) | Cloud Run | Elastic Beanstalk / App Runner |
| REST API (FastAPI) | Cloud Run | API Gateway + Lambda / App Runner |
| Agent Worker (FastAPI) | Cloud Run | ECS Fargate / Lambda |
| Job Queue | Cloud Tasks | SQS |
| Relational Database | Cloud SQL (PostgreSQL) | RDS PostgreSQL |
| Vector Store | pgvector extension on Cloud SQL | RDS + pgvector |
| Secrets | Secret Manager | Secrets Manager |
| Container Registry | Artifact Registry | ECR |
| Scheduled Research | Cloud Scheduler | EventBridge Scheduler |
| Authentication | Clerk (third-party, same on both) | Cognito |
| LLM Calls | OpenRouter API | Amazon Bedrock |

**How it works end-to-end:**
1. The user logs in via Clerk and views their portfolio on the Next.js frontend hosted on Cloud Run.
2. They click "Run Analysis". The frontend calls the FastAPI REST API (also on Cloud Run).
3. The API creates a `job` record in Cloud SQL, then enqueues a task to Cloud Tasks (analogous to pushing a message onto SQS).
4. Cloud Tasks invokes the single agent worker service via an authenticated HTTP POST.
5. The agent fetches the user's portfolio from Cloud SQL, constructs a prompt, and calls the LLM through OpenRouter (replacing AWS Bedrock). The structured response is written back to the `jobs` table.
6. The frontend polls the API every few seconds until the job is marked complete, then renders the report and charts.

All services are containerised with Docker and deployed to Cloud Run, which scales to zero when idle - keeping costs near zero for a project workload. Infrastructure is managed with Terraform across four modules: database, agent worker, API, and frontend.