ZoomProp Context Engine Document

Repository: zoomprop/zp-alpha Product: ZoomProp AI Platform Version: 0.1.0 (v0.1 Spark → v0.3 Scaffold) Document Type: Context Engineering Specification Document ID: TECH-CE-001

---

Table of Contents

1. Executive Summary
2. Domain Profile
3. Context Architecture
4. Prompt Engineering Patterns
5. Memory Management
6. Agent Context Protocols
7. Knowledge Graph Structure
8. Context Density Strategies
9. Cross-Session Persistence Model
10. ID Registry and Cross-Reference Map

---

1. Executive Summary

ZoomProp is an AI-native real estate investment platform. The platform exposes at least 17 distinct AI API routes (/api/ai/*), orchestrates multi-step LLM workflows via LangChain and LangGraph, and maintains a dedicated context/ directory containing over 30 architectural and operational documents that function as a living knowledge base for AI-assisted development and agent execution. This document defines how context flows through that system — from raw repository knowledge, through agent protocols, to per-request prompt assembly — and establishes the canonical reference for all contributors and automated agents operating within the zp-alpha repository.

---

2. Domain Profile

2.1 Product Domain

ZoomProp operates in the residential and commercial real estate investment domain. Its primary users are individual investors, portfolio managers, and co-investment groups who evaluate, track, and act on property investment opportunities. The platform bridges property discovery, financial underwriting, portfolio management, and AI-assisted decision support within a single interface.

2.2 Key Entities

2.3 Core Terminology

2.4 Domain Constraints

• TECH-CON-001: All financial calculations (cap rate, NOI, cash flow) must be validated against CapRateBaseSchema before being passed to LLM prompts. Raw string values must be parseFloat-normalized before prompt injection.
• TECH-CON-002: LLM responses that produce financial estimates must be framed as informational, not fiduciary advice. Prompts must include appropriate disclaimer framing.
• TECH-CON-003: Geographic data is dual-sourced: Mapbox for visual rendering (NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN) and Google Maps for static imagery (maps.googleapis.com). Prompts referencing location must use the resolved address string, not raw coordinates.
• TECH-CON-004: Multi-tenancy is enforced at the Clerk organization layer. AI requests must carry the active organization ID. The /api/auth/active-org/route.ts endpoint is the canonical source of the scoped org context.
• TECH-CON-005: LangChain, @langchain/core, and @langchain/community are declared as serverExternalPackages in next.config.ts, meaning they execute only in Node.js server contexts and must never be imported in client components.

---

3. Context Architecture

3.1 Structural Overview

ZoomProp's context architecture has three distinct layers:

┌─────────────────────────────────────────────────────────┐
│  Layer 3: Repository Knowledge Base (context/ directory) │
│  Static documents, architecture guides, action plans     │
├─────────────────────────────────────────────────────────┤
│  Layer 2: Runtime Context Assembly (API routes)          │
│  Per-request prompt construction, conversation history   │
├─────────────────────────────────────────────────────────┤
│  Layer 1: Persistent State (conversations, portfolios)   │
│  Database-backed session and entity context              │
└─────────────────────────────────────────────────────────┘

3.2 Layer 3 — Repository Knowledge Base

The context/ directory contains 30+ markdown documents that serve as the authoritative knowledge corpus for AI-assisted development and agent task execution. These documents are not passive documentation — they are the primary mechanism by which project state is communicated across sessions, developer handoffs, and AI agent invocations.

Key documents and their context roles:

The .cursor/mcp.json file and .claude/settings.local.json indicate that AI editor agents (Cursor, Claude Code) are configured to consume this context/ layer directly, establishing it as a first-class context source for development-time agents.

3.3 Layer 2 — Runtime Context Assembly

Runtime context is assembled at the API route level. The 17 active AI routes each represent a distinct context assembly strategy:

3.4 Layer 1 — Persistent State

Persistent context lives in two stores:

Conversation persistence (/api/ai/conversations, /api/ai/conversations/:id): Each conversation is stored with its full message history and is retrievable by ID. The /api/ai/generate-title route generates a human-readable title from the conversation content, implying a summarization step that produces a durable label used in UI navigation.

Portfolio and entity state: Properties, portfolios, alerts, and collections are stored in the ZoomProp backend API (NEXT_PUBLIC_ZOOMPROP_API_URL_V1). AI routes that need entity context fetch it from this API rather than from the LLM, ensuring ground truth financial data is never hallucinated.

---

4. Prompt Engineering Patterns

4.1 Intent Classification Pattern (PTRN-001)

Route: src/app/api/ai/intent/route.ts

The intent route classifies raw user input before routing it to a specialized analysis chain. This is a gating pattern: the LLM first determines what the user is asking (property analysis, market comparison, cap rate calculation, general Q&A) before the appropriate context is assembled for the substantive response. This prevents unnecessary context injection and keeps token usage proportional to query complexity.

User Input → /api/ai/intent → IntentLabel → Route to specialized /api/ai/{intent} → Response

4.2 Persona-Scoped Prompting (PTRN-002)

Route: src/app/api/ai/personas/route.ts

The personas system allows users to configure an AI behavioral profile. A persona modifies the system prompt layer — adjusting expertise framing (e.g., "experienced multifamily underwriter" vs. "first-time investor guide"), verbosity, and the financial assumptions the model defaults to. Persona configuration is resolved before any substantive prompt is built, making it a global system-prompt modifier.

4.3 Financial Validation Gate (PTRN-003)

Schema: CapRateBaseSchema, CapRateCalculationSchema

Before any financial data enters a prompt, it is passed through Zod schemas that normalize string inputs (parseFloat with comma stripping), enforce range constraints (constVacancy 0–100, constOperExpenses 0–100), and apply defaults (constVacancy: 5, constOperExpenses: 30, constResEstimate: 5, constClosingCosts: 2). This ensures that LLM inputs for financial calculations are always well-typed numbers, eliminating a class of hallucination where the model receives ambiguous or malformed financial strings.

4.4 Artifact Generation Pattern (PTRN-004)

Documents: chat-onboarding/CHAT_SYSTEM_DESIGN_AND_LIFECYCLE.md, PR #462

Chat responses can contain structured artifacts — self-contained outputs such as action plans (M1–M5 milestone structures), inspection summaries, or offer recommendations. Artifacts are generated through a distinct prompt pass that requests structured output (likely JSON or markdown with defined schema), separate from the conversational response. This separation ensures the artifact is machine-parseable for rendering while the chat text remains natural.

4.5 Contextual Suggestion Pattern (PTRN-005)

Route: src/app/api/ai/suggestions/route.ts

After each AI interaction, the suggestions route generates 3–5 follow-up questions or actions. These are derived from the current conversation state and the entity in focus. The quick actions grid (PR #362) surfaces these as clickable chips in the chat UI (QuickActionsGrid). This pattern maintains conversational momentum and reduces user cognitive load by making the next relevant query zero-effort.

4.6 AI Search Template Pattern (PTRN-006)

Route: src/app/api/ai-search-templates/route.ts

Search templates are persisted prompt structures that users can save and reuse. A template encapsulates a query intent, filter set, and natural language description. When invoked, the template provides a pre-structured context block that replaces the cold-start ambiguity of an open-ended search prompt.

4.7 Multi-Step Investigation Chain (PTRN-007)

Route: src/app/api/actions/analyze-property-investigation/route.ts

The property investigation route executes a multi-step LangGraph workflow rather than a single LLM call. Each step in the graph receives the output of the previous step as context, enabling progressive refinement: initial property scan → financial assessment → risk identification → recommendation synthesis. This is the highest-context-density pattern in the system and is where LangGraph's state management is most critical.

---

5. Memory Management

5.1 Context Window Budget

ZoomProp uses @ai-sdk/openai (v2.0.30) and @langchain/openai (v0.5.16), both of which target GPT-4-class models with 128k token windows. Despite this headroom, the platform employs a tiered context inclusion strategy to keep latency and cost proportional to query value:

5.2 Rolling Conversation Window

Conversation history is fetched from /api/ai/conversations/:id. Rather than injecting the full history into every prompt, the system applies a rolling window strategy. The /api/ai/generate-title route produces a compressed title from the conversation, suggesting that a summarization step is available to collapse older turns into a summary token when the history approaches window pressure.

5.3 Cross-Session Summarization

When a conversation session ends or when the user navigates away, the title generation route (/api/ai/generate-title) is invoked to produce a durable summary label. This label serves as the compressed representation of the session for future retrieval and as a context prefix if the user resumes the conversation in a new session.

5.4 Free Query Quota as Context Signal

Commit 3a74c26 introduces a monthly free query grant for unpaid users with context integration. The quota state (queries remaining) is injected into the context layer, which allows the system prompt to adjust its response strategy (e.g., more concise responses, deferred deep analysis) when approaching the limit. This is a novel use of system-state as a context modifier.

5.5 Elastic Search Integration

The @elastic/elasticsearch (v8.18.2) dependency and legacy routes in archive/legacy-api-backup/elastic-search/ indicate that semantic or keyword search over the property corpus is available. In the current active routes, Elastic is used to back the address and region search functions, which provide structured entity resolution before LLM context assembly. This prevents the LLM from needing to interpret ambiguous location strings.

---

6. Agent Context Protocols

6.1 Development-Time Agents

ZoomProp explicitly supports AI code-generation agents (Cursor, Claude Code) through configuration files at .cursor/mcp.json and .claude/settings.local.json. These agents are directed to consume the context/ directory as their primary knowledge source.

Protocol AGNT-DEV-001 — Development Agent Initialization:

1. Load context/README.md as the entry point.
2. Load context/ARCHITECTURE.md for structural constraints.
3. Load context/LLM_ARCHITECTURE.md before touching any src/lib/ai/ or src/app/api/ai/ file.
4. Load context/DESIGN_SYSTEM.md before generating or modifying any UI component.
5. Load the relevant feature-specific document (e.g., context/CHAT_SYSTEM_OVERVIEW.md for chat work) before making changes.

Protocol AGNT-DEV-002 — Action Plan Execution: The context/ACTION_PLAN.md and feature-specific action plans (e.g., context/DISCOVER_PAGE_ACTION_PLAN.md, context/COLLECTIONS_IMPLEMENTATION_ACTION_PLAN.md) encode phased implementation tasks. Agents executing these plans must read the plan document first, check context/INTEGRATION_STATUS.md for current phase state, and update the status document after completing each milestone.

6.2 Runtime AI Agents

Protocol AGNT-RT-001 — Chat Agent: The /api/ai/chat agent receives: (1) system prompt with persona modifier, (2) conversation history (rolling window), (3) active entity context if a property or region is selected, (4) user message. It returns a streaming response plus triggers the suggestions route post-response.

Protocol AGNT-RT-002 — Property Investigation Agent: The /api/actions/analyze-property-investigation agent is a LangGraph multi-node workflow. Each node receives the accumulated graph state from prior nodes. The initial node receives the full property entity plus any user-provided investigation parameters. Subsequent nodes receive only the outputs of prior nodes plus the original property ID as a stable anchor.

Protocol AGNT-RT-003 — Commercial Analysis Agent: /api/ai/commercial-analysis and /api/ai/commercial-estimates are specialized agents that receive pre-validated CapRateCalculationInput objects (post-Zod transform) as their financial context. These agents are not general-purpose; their system prompts are scoped exclusively to commercial real estate underwriting.

Protocol AGNT-RT-004 — Intent Router: /api/ai/intent acts as a dispatch agent. It receives only the raw user message (no history, no entity context) and returns a structured intent classification. This keeps the intent call minimal and fast. The response from this agent determines which downstream agent protocol is invoked.

6.3 Context Handoff Between Agents

When the investigation chain (AGNT-RT-002) produces an artifact, that artifact is stored as a structured message in the conversation via /api/ai/conversations/:id. The chat agent (AGNT-RT-001) can then reference this artifact in subsequent turns by retrieving it from conversation history. This creates an implicit shared memory between the investigation agent and the chat agent without requiring direct agent-to-agent communication.

---

7. Knowledge Graph Structure

7.1 Graph Topology

The ZoomProp knowledge graph is implemented as a document-ID cross-reference network rather than a formal graph database. Nodes are documents, API routes, UI components, and database entities. Edges are explicit references within documents (e.g., action plans referencing architecture docs) and implicit references via shared ID tokens.

context/README.md
    ├── → context/ARCHITECTURE.md (TECH-ARCH-001)
    ├── → context/LLM_ARCHITECTURE.md (TECH-LLM-001)
    ├── → context/CHAT_SYSTEM_OVERVIEW.md (TECH-CHAT-001)
    ├── → context/DESIGN_SYSTEM.md (TECH-DS-001)
    └── → context/PRODUCT_REALIZATION_ROADMAP.md (TECH-PRR-001)

context/LLM_ARCHITECTURE.md (TECH-LLM-001)
    ├── → src/app/api/ai/* (API-AI-001 through API-AI-017)
    ├── → src/lib/ai/__tests__/portfolio-context-analysis.test.ts
    └── → @langchain/langgraph, @langchain/openai, @ai-sdk/openai

context/CHAT_SYSTEM_OVERVIEW.md (TECH-CHAT-001)
    ├── → /api/ai/chat (API-AI-001)
    ├── → /api/ai/conversations (API-AI-015)
    ├── → /api/ai/suggestions (API-AI-010)
    └── → chat-onboarding/CHAT_SYSTEM_DESIGN_AND_LIFECYCLE.md (TECH-CHAT-002)

7.2 Entity Cross-Reference Table

7.3 Context Document Dependency Order

For any agent or developer entering the codebase, documents must be consumed in this dependency order to avoid contradictory or incomplete context:

1. context/README.md — orientation
2. context/ARCHITECTURE.md — system boundaries
3. context/LLM_ARCHITECTURE.md — AI subsystem specifics
4. Feature-specific context document (e.g., context/DISCOVER_PAGE_COMPREHENSIVE_DOCUMENTATION.md)
5. Relevant action plan (e.g., context/DISCOVER_PAGE_ACTION_PLAN.md)
6. Status document (context/INTEGRATION_STATUS.md, context/QA_STATUS.md)

7.4 Archive as Negative Knowledge

The archive/legacy-api-backup/ directory contains 80+ deprecated route implementations (chat, Plaid, Stripe, Middesk, Hellosign, etc.). This archive constitutes negative knowledge in the knowledge graph — agents must be explicitly instructed that files under archive/ represent superseded patterns and must not be used as implementation references. The context/CODEBASE_ANALYSIS.md document should encode this constraint.

---

8. Context Density Strategies

8.1 Structured Data Over Prose

When passing property or financial data to an LLM, the platform uses Zod-validated typed objects rather than natural language descriptions. A property passed as { listPrice: 450000, constMonthlyRent: 2800, constVacancy: 5, constOperExpenses: 30 } consumes approximately 40 tokens and is unambiguous. The equivalent prose description would consume 3–4× the tokens and introduce interpretation variance. This is PTRN-003 applied as a density strategy.

8.2 Intent-First Routing

Because /api/ai/intent classifies queries before context assembly, the system avoids injecting full portfolio, market, and conversation history into simple factual queries. A question like "What is the cap rate formula?" triggers a minimal-context response path; a question like "Should I buy this property?" triggers T0–T4 context injection. This routing saves 2,000–8,000 tokens per simple query.

8.3 Persona as System Prompt Compression

Rather than re-stating behavioral constraints in every prompt ("be concise," "use real estate terminology," "assume institutional investor knowledge"), the persona system encodes these as a named profile resolved once per session. The resolved persona token replaces what would otherwise be 200–500 tokens of behavioral instruction per request.

8.4 Elastic Pre-Resolution

Before property or region data enters an LLM prompt, it is resolved through Elasticsearch to a canonical entity with structured fields. This prevents the LLM from receiving raw user-typed location strings (e.g., "that place in Austin near the lake") and having to interpret them. Pre-resolution ensures the LLM receives { city: "Austin", state: "TX", neighborhood: "Barton Hills", zipCode: "78704" } rather than ambiguous natural language.

8.5 Artifact Isolation

Chat artifacts (action plans, inspection summaries) are generated in separate API calls with their own prompts optimized for structured output. They do not share a token budget with the conversational response. This prevents the artifact generation instructions from diluting the conversational response quality, and vice versa.

8.6 Free Query Quota as Density Signal

When a user's free query quota is low (from the grant system in commit 3a74c26), the context layer can signal to the response-generation prompt to produce more concise output. This is an adaptive density strategy: context density targets are adjusted at runtime based on platform economics, not just query complexity.

---

9. Cross-Session Persistence Model

9.1 Session Identity

Sessions are scoped by the Clerk authentication layer. Each request carries a userId and organizationId resolved via /api/auth/session/route.ts and /api/auth/active-org/route.ts. These IDs are the primary keys for all session-scoped context retrieval — conversation history, portfolio state, persona configuration, and alert preferences are all keyed to this identity tuple.

9.2 Conversation Continuity

The conversation persistence model at /api/ai/conversations and /api/ai/conversations/:id enables full cross-session continuity. A user returning to a conversation after logout/login retrieves the same message history. The generated title (from /api/ai/generate-title) provides a recognizable handle for re-entry. No re-orientation prompt is needed because the full message history is available.

9.3 Portfolio Context Persistence

Portfolio state is persisted in the ZoomProp backend (NEXT_PUBLIC_ZOOMPROP_API_URL_V1) and is not session-dependent. The portfolio context analysis test at src/lib/ai/__tests__/portfolio-context-analysis.test.ts validates that portfolio-level context is correctly assembled from this persisted state, confirming it as a first-class context source for AI routes.

9.4 Onboarding State as Persistent Context

The multi-step onboarding wizard (src/app/(auth)/onboarding/) captures structured user preferences — geographic focus (geographic-focus-step.tsx), investment interests (investment-interests-step.tsx), portfolio count (portfolio-count-step.tsx), platform goals (platform-goals-step.tsx), and co-investment preferences (co-investment-step.tsx). This onboarding data is stored as user/org metadata via Clerk and is retrievable as a persistent context block that shapes all subsequent AI interactions for that user.

9.5 Alert Configuration as Context Memory

Alert configurations (/api/alerts/configure, /api/alert-filters) represent a form of long-term user intent memory. The thresholds and criteria a user has configured for alerts encode their investment criteria, which can be injected into property analysis prompts to personalize evaluations against the user's own stated parameters.

---

10. ID Registry and Cross-Reference Map

10.1 Technical Component IDs

10.2 API Route IDs