CFAI Stock Analysis Platform

AI-powered stock analysis platform with event-driven backend (Motia) and Next.js 15 frontend. Provides real-time DCF analysis, business quality ratings, and portfolio recommendations.

Architecture Overview

This is a Turborepo monorepo with two independent services sharing a database:

`apps/backend`: Motia event-driven analysis engine (port 3001)

`apps/web`: Next.js 15 frontend with NextAuth (port 3000)

`packages/db`: Shared Prisma schema and client

`packages/types`: Shared Zod schemas exported by both services

**Critical Rule**: Backend and web communicate ONLY via HTTP APIs, real-time streams, and shared database. Never import backend code into web or vice versa—use shared packages (`@repo/types`, `@repo/db`).

Backend Development (Motia Framework)

Core Primitive: Steps

Every backend feature is a **Step** (`*.step.ts`) with two exports:

`config`: Type, schemas, event subscriptions/emissions

`handler`: Async function that executes the logic

Step Types

1. **API Steps**: HTTP endpoints that emit events and return immediately

2. **Event Steps**: Background processing triggered by events (AI analysis, DCF calculations)

3. **Cron Steps**: Scheduled tasks

4. **Stream Steps**: Real-time WebSocket updates (`.stream.ts`)

Event-Driven Pattern

```typescript

// API Step: Emit event immediately

await emit({ topic: "process-stock-analysis", data: { symbol } });

// Event Step: Subscribe to topic

export const config = {

subscribes: ["process-stock-analysis"],

// ...

};

```

State Management (Critical)

**Write state:**

```typescript

await state.set("dcf-results", traceId, dcfData);

```

**Read state (ALWAYS use validation):**

```typescript

import { getValidatedState } from "./lib/statehooks";

const dcf = await getValidatedState(

"dcf-results",

dcfResultSchema,

state,

traceId,

logger

);

```

**Why validation is required**: Ensures type safety and runtime correctness between decoupled event-driven steps.

Real-Time Streams

Update clients via WebSocket streams:

```typescript

streams["stock-analysis-stream"].set("analysis", traceId, {

status: "Calculating DCF...",

progress: 60

});

```

Clients automatically receive updates via `@motiadev/stream-client-react`.

Type Generation (Non-Negotiable)

After ANY config change in backend:

```bash

cd apps/backend

npx motia generate-types

```

This auto-generates `types.d.ts` with type-safe `Handlers` interface. Every step MUST export its Zod schema to `packages/types`.

Frontend Development (Next.js 15)

Component Architecture (Four Analysis Pillars)

1. **Business Quality** (`BusinessQualityCard`): Moat strength, tier rating, market structure

2. **Valuation Reality** (`FeasibilityGauge`): Price vs. growth feasibility (5 scenarios)

3. **Action** (`AllocationCard`): Buy/Hold/Sell recommendation, portfolio role, risk level

4. **Sensitivity** (`SensitivityTable`): DCF matrix (discount rate × terminal growth)

Data Flow

**Current**: Mock data in `(marketing)/page.tsx`

**Future**: Connect to `stock-analysis-stream` for real-time updates

Styling

Tailwind CSS with `lucide-react` icons for consistency.

AI & Financial Logic

AI Provider

Vercel AI SDK with Gemini models:

```typescript

import { google } from "@ai-sdk/google";

import { generateObject } from "ai";

const result = await generateObject({

model: google("gemini-2.0-flash-exp"),

schema: growthJudgementSchema,

prompt: "Analyze growth trajectory...",

});

```

Key AI Functions (in `apps/backend/steps/lib/ai-functions/`)

`parseThesis.ts`: Extract Porter's 5 Forces, growth drivers from research

`judgement.ts`: Predict realistic growth vs. market-implied growth

`rating.ts`: Comprehensive qualitative rating (Tier, Moat, Action)

Financial Models

**Reverse DCF**: Solves for implied growth rate given current price

**Forward DCF**: Calculates intrinsic value from AI's growth projection

**Sensitivity Analysis**: 5×5 matrix (discount rate ±1% × terminal growth ±0.5%)

Database Schema (Prisma)

Key Models

`User`: NextAuth user with `hasAccess` boolean (closed beta flag)

`AnalysisResult`: Cached stock analysis (1 per ticker per TTL), stores JSON blobs (`thesis`, `dcf`, `rating`)

`UserQuery`: Tracks user requests with `traceId` for real-time updates

**Access Pattern**: Backend writes via `@repo/db`, frontend reads via server actions/API routes.

Critical Workflows & Commands

```bash

Start everything

pnpm dev # Root (runs both backend + web)

Backend only

cd apps/backend

pnpm dev # Starts Motia Workbench at :3001

npx motia generate-types # Regenerate types after config changes

Database

cd packages/db

npx prisma migrate dev # Create migration

npx prisma studio # Visual DB browser

Type checking

pnpm run check-types # Validates all workspace types

```

Critical Patterns & Conventions

Shared Types

Always export schemas from `packages/types/src/*.ts`:

```typescript

// packages/types/src/dcf.ts

export const dcfResultSchema = z.object({...});

// Backend or frontend

import { dcfResultSchema } from "@repo/types";

```

State Validation

Never use `state.get()` directly—use `getValidatedState()`:

```typescript

const dcf = await getValidatedState(

"dcf",

dcfResultSchema,

state,

traceId,

logger

);

```

Event Chaining

Declare all emitted events in step config:

```typescript

export const config = {

emits: ["finish-dcf"],

// ...

};

// Downstream step subscribes

export const otherConfig = {

subscribes: ["finish-dcf"],

// ...

};

```

Real-Time Updates

Stream status updates at each step boundary:

```typescript

streams["stock-analysis-stream"].set("analysis", traceId, {

status: "Calculating DCF...",

progress: 60,

currentStep: "dcf"

});

```

Deployment Architecture

**⚠️ CRITICAL**: Frontend and backend MUST be deployed separately.

Why Separate Deployments

Motia requires persistent WebSocket connections and long-running BullMQ workers

Vercel serverless functions timeout after 60-300s (incompatible with Motia)

Backend needs Redis for state management and job queuing

Recommended Setup

```

Frontend (apps/web) → Vercel (Next.js serverless)

Backend (apps/backend) → Motia Cloud (managed Motia hosting)

Database → Vercel Postgres (shared)

```

Alternative (Self-Hosted)

```

Frontend (apps/web) → Vercel

Backend (apps/backend) → Railway/Render (Docker + Redis)

Database → Vercel Postgres

```

Environment Variables

Vercel manages env vars via dashboard UI (no `.env` files in deployment)

See `.env.example` for all required variables

`turbo.json` configured with `env` arrays for proper cache invalidation

Different `NEXTAUTH_SECRET` for staging vs production

See `.github/DEPLOYMENT.md` for step-by-step deployment instructions.

Common Pitfalls

1. **Missing Types**: If TypeScript errors appear in handlers, run `npx motia generate-types`

2. **Direct State Access**: Using `state.get()` without validation causes silent type mismatches

3. **Heavy API Logic**: API steps should emit events, not perform compute (use Event steps)

4. **Schema Drift**: Always re-export schemas from `packages/types` to keep frontend/backend in sync

5. **Overlapping Concerns**: Keep "Quality" (business strength) separate from "Valuation" (price vs. growth math)

6. **Deploying Backend to Vercel**: Will fail silently or timeout—use Docker/Railway instead

Examples

Creating a New Analysis Step

```typescript

// apps/backend/steps/new-analysis.step.ts

import { getValidatedState } from "./lib/statehooks";

import { analysisSchema } from "@repo/types";

export const config = {

type: "event" as const,

subscribes: ["start-analysis"],

emits: ["analysis-complete"],

schemas: {

data: z.object({ symbol: z.string() }),

output: analysisSchema,

};

export const handler: Handlers["new-analysis"] = async ({

data,

state,

traceId,

logger,

emit,

streams,

}) => {

// Update UI

streams["stock-analysis-stream"].set("analysis", traceId, {

status: "Running analysis...",

});

// Perform analysis

const result = await performAnalysis(data.symbol);

// Save to state

await state.set("analysis", traceId, result);

// Emit completion

await emit({

topic: "analysis-complete",

data: { symbol: data.symbol },

});

return result;

};

```

Connecting Frontend to Stream

```typescript

// apps/web/app/analysis/[symbol]/page.tsx

"use client";

import { useStream } from "@motiadev/stream-client-react";

export default function AnalysisPage({ params }) {

const { data, isConnected } = useStream({

url: `${process.env.NEXT_PUBLIC_BACKEND_URL}/streams/stock-analysis-stream`,

traceId: params.symbol,

});

return (

<div>

<p>Status: {data?.status}</p>

<p>Progress: {data?.progress}%</p>

</div>

);

}

```

Constraints

Backend and web must remain independent (no direct imports)

All shared code goes through `packages/types` or `packages/db`

Always validate state with Zod schemas

Regenerate types after every backend config change

Never deploy backend to Vercel (use Motia Cloud or Docker hosting)

API steps emit events, Event steps do heavy work

Stream updates at every step boundary for UX

CFAI Stock Analysis Platform

CFAI Stock Analysis Platform

Architecture Overview

Backend Development (Motia Framework)

Core Primitive: Steps

Step Types

Event-Driven Pattern

State Management (Critical)

Real-Time Streams

Type Generation (Non-Negotiable)

Frontend Development (Next.js 15)

Component Architecture (Four Analysis Pillars)

Data Flow

Styling

AI & Financial Logic

AI Provider

Key AI Functions (in `apps/backend/steps/lib/ai-functions/`)

Financial Models

Database Schema (Prisma)

Key Models

Critical Workflows & Commands

Start everything

Backend only

Database

Type checking

Critical Patterns & Conventions

Shared Types

State Validation

Event Chaining

Real-Time Updates

Deployment Architecture

Why Separate Deployments

Recommended Setup

Alternative (Self-Hosted)

Environment Variables

Common Pitfalls

Examples

Creating a New Analysis Step

Connecting Frontend to Stream

Constraints

Reviews (0)