Beleggen Coach: hoe ik een AI-gedreven beleggingsapp bouwde met MCP, Copilot agents en een monorepo

Beleggen is voor veel mensen een drempel vol jargon, angst en onzekerheid. Toch is vroeg beginnen met eenvoudige, gespreide ETF-beleggingen één van de krachtigste manieren om vermogen op te bouwen. Ik bouwde Beleggen Coach als een persoonlijk project om die drempel te verlagen — een slimme app die beginners begeleidt van profiel tot concreet beleggingsplan, aangedreven door AI en domeinspecifieke data. In deze publieke case study focus ik op de productarchitectuur, UX-flow en technische keuzes, zonder de private broncode of interne repositorystructuur bloot te geven.

Wat is Beleggen Coach?

Beleggen Coach is een full-stack webapplicatie die een gebruiker begeleidt door een gestructureerd onboardingproces: profiel opstellen, risicotolerantie bepalen, ETF-suggesties krijgen op maat en een persoonlijk beleggingsplan genereren. Onder de motorkap werkt het platform met een duidelijke scheiding tussen frontend, backend en zes domeinspecifieke MCP-services die elk een specifiek deel van de beleggingsflow aansturen.

Architectuur in lagen

Voor de publieke portfolio volstaat het om de oplossing in lagen te tonen. Zo blijft de architectuur helder voor bezoekers van vorsters.dev, terwijl de private implementatiedetails en interne code-structuur afgeschermd blijven.

• Een Next.js frontend voor onboarding, ETF-overzichten en het persoonlijke beleggingsplan.
• Een FastAPI backend die profieldata, aanbevelingslogica en planopbouw orkestreert.
• Zes MCP-services voor profielintelligentie, ETF-screening, marktdata, plansimulatie, gedragscoaching en leercontent.
• Een gedeelde product- en documentatielaag zodat features, copy en AI-flow consistent kunnen evolueren.

De systeemarchitectuur

De architectuur volgt een gelaagd model. De Next.js frontend communiceert via REST/JSON met de FastAPI backend. De backend beheert de PostgreSQL database (via SQLAlchemy async) en een Redis cache voor sessiedata en snelle opzoekingen. Daaronder hangen de MCP servers als autonome modules die via het stdio-protocol aangesproken worden door Copilot. Externe diensten zoals Clerk (authenticatie), OpenAI API (AI chat) en Yahoo Finance (live koersen) worden op de juiste lagen geïntegreerd.

De zes MCP servers uitgelegd

Het hart van het AI-aspect van Beleggen Coach is het netwerk van zes domeinspecifieke MCP servers. Elk bedient een specifiek expertisedomein en kan onafhankelijk worden getest, gedeployed en geüpgraded. Dit is een fundamenteel ander patroon dan één grote AI-aanroep: kennis is verdeeld over specialisten.

Custom Copilot Agents als AI-ontwikkelteam

Naast de runtime-MCP-servers bevat het project ook custom Copilot agents in .github/agents/. Dit zijn gespecialiseerde agents die ik gebruik tijdens de ontwikkeling zelf — niet op productie. Ze kennen de volledige codebase, de architectuurprincipes en de product-specs. Zo heb ik agents voor frontend componenten, API-routers, database-migraties en productanalyse die elk hun eigen expert-context meekrijgen via een gedetailleerde agent.md instructie.

# .github/copilot-instructions.md (fragment)

## Stack
- Frontend: Next.js 14 App Router, TypeScript, Tailwind CSS
- Backend: FastAPI, Python 3.12, SQLAlchemy 2.0 async, Alembic
- Database: PostgreSQL (via Docker), Redis
- Package manager: pnpm (monorepo), uv (Python)
- MCP: stdio protocol, elk eigen Python-package

## Principes
- Gebruik altijd async/await in FastAPI routes
- MCP tools returnen altijd { success: bool, data: ..., error: str | None }
- TypeScript strict mode — geen any-types
- Elke nieuwe feature begint met een migratie-bestand

Fase 6: de roadmap

Het project is opgezet in fasen. De eerste vijf fasen legden de fundering: onboarding flow, ETF-database, beleggingsplan, leercentrum en maandelijkse check-in. Fase 6 brengt het platform naar een volwassen productieniveau met zeven grote toevoegingen: login & authenticatie via Clerk, een volledig uitgebreid dashboard, AI-chatinterface met streaming, top-3 ETF-aanbevelingen op basis van live marktdata, portefeuille-opvolging, analytisch overzicht en een gecureerde bronpagina.

AI Chat met guardrails

De AI-chatfunctie is technisch interessant én verantwoordelijk complex. De chat-router in FastAPI stuurt de gebruikersvraag naar OpenAI GPT-4o met een systeem-prompt die de context bevat: gebruikersprofiel, huidig plan, en relevante ETF-data opgehaald via MCP. Streaming via Server-Sent Events zorgt voor een vloeiende gebruikerservaring. Wat ik bewust niet doe: expliciete koopadvies geven. De guardrails in de systeem-prompt zorgen dat de AI altijd een disclaimer toevoegt en geen "koop nu" statements maakt.

# apps/api/src/routers/chat.py (vereenvoudigd)
@router.post("/chat")
async def chat(request: ChatRequest, user: TokenData = Depends(get_current_user)):
    profile = await get_user_profile(user.user_id)
    etf_context = await etf_data_mcp.get_top3_for_profile(profile.id)
    
    system_prompt = f"""
    Je bent een beleggingscoach voor beginners.
    Gebruikersprofiel: {profile.model_dump_json()}
    Huidige Top 3 ETFs: {etf_context}
    
    REGELS:
    - Geef nooit expliciete koop- of verkoopadvies
    - Voeg altijd toe: "Dit is geen financieel advies."
    - Leg termen uit in gewone taal
    - Verwijs door naar een financieel adviseur bij complexe vragen
    """
    
    async for chunk in openai_stream(system_prompt, request.messages):
        yield f"data: {chunk}\n\n"

Wat ik leerde van dit project

• MCP is een game-changer voor AI-geïntegreerde applicaties: kennis opdelen in domeinspecifieke servers maakt het systeem veel onderhoudbaarder dan één grote AI-aanroep
• uv als Python package manager is razendsnel — een volledige sync van een nieuw project duurt seconden in plaats van minuten
• pnpm monorepo + turborepo zorgt voor een nette scheiding maar vereist discipline in het beheer van gedeelde types
• Guardrails in de systeem-prompt zijn niet optioneel voor een financiële applicatie — ze zijn de eerste verdedigingslinie tegen onjuist advies
• Redis als cache voor ETF-data vermijdt dat elke gebruikersinteractie een dure API-call triggert naar Yahoo Finance of Alpha Vantage
• Custom Copilot agents tijdens ontwikkeling versnellen het werk aanzienlijk — ze kennen de architectuurprincipes en code-conventies beter dan een generieke AI

De beste beleggingsapp is niet de slimste — het is de meest begrijpbare. AI helpt niet door het antwoord te geven, maar door de vraag te verduidelijken.

De code bekijken

De broncode van Beleggen Coach blijft bewust privé. In deze write-up deel ik wel de architectuurkeuzes, de productstructuur en de belangrijkste lessen uit de bouw van het platform, zonder de volledige implementatie publiek te maken.