# APEX Agentic Platform Technical Plan ## Purpose This document defines the technical plan for the APEX agentic operations platform. It is not the client-facing proposal. It is the implementation-oriented source of truth for architecture, workflow design, trust controls, integration strategy, CRM validation, milestone delivery, risks, and handoff requirements. The platform should be built as a TypeScript product on NestJS and Next.js, not as a loose Python automation stack. The first technical objective is to create a trusted internal operations layer for APEX: one place to see operational status, workflow exceptions, approval queues, source-system context, and next actions. Agentic behavior should be introduced through bounded workflows, typed tools, explicit context, and human approval controls. The delivery posture is read-first, write-later. Early milestones should read source systems, detect exceptions, summarize status, draft next actions, and queue approvals. Write access into live systems should expand only after the team trusts the data model, source-of-truth map, approval policy, audit trail, and integration reliability. ## Product Boundary The first product is a trusted brokerage command center for internal operations, not a full CRM replacement, partner portal, or SaaS product. The command center should answer: - What needs attention today? - Which workflows are stuck? - Who owns the next action? - Which statuses are confirmed, inferred, stale, or waiting for review? - Which actions require approval before touching a client, partner, compliance record, or external system? - Which source system produced the current status? - What changed since the last operational review? The first screen should be "Today at APEX": exceptions, approvals, stuck workflows, agent tasks, listing launches, transaction risks, partner handoffs, and workflow results. Chat can support the experience, but the primary product surface should be status, next action, source visibility, approval, and audit. ## Architecture Principles 1. **Workflow-first, agent-assisted.** Repeatable brokerage processes are defined as declarative flowkit flows in YAML and run as durable BullMQ jobs. Agents handle judgment, triage, summarization, routing, exception recovery, and drafting from inside those flows, not around them. 2. **Clean front/back boundary.** Next.js renders and calls the API. All business logic, orchestration, external-system access, and data ownership live in NestJS. The frontend holds no business rules. 3. **Typed adapters for every external system.** Agentic workers should never call raw third-party APIs directly. Each system is wrapped with typed service modules that enforce permissions, retries, logging, rate limits, and error handling. 4. **Read-first automation.** Early milestones should default to read-only analysis, status classification, exception detection, and approval queues. 5. **Human approval for risky actions.** Customer-visible, partner-visible, compliance-sensitive, bulk, irreversible, or external writes require explicit approval unless a narrow pre-approved rule exists. 6. **Transparent status.** Every important dashboard status should show source system, last sync time, confidence/state, owner, next action, stale-data warnings, approval history, and manual correction path. 7. **Source-of-truth by object type.** Contacts, tasks, transactions, documents, listings, marketing status, approvals, workflow run history, and partner updates need explicit ownership rules. 8. **Milestone gates.** Each milestone must produce evidence that supports a go, pivot, or stop decision before additional scope is funded. 9. **Internal proof before external packaging.** Partner integration and SaaS hardening should follow measurable internal ROI, not precede it. ## Stack The stack is fixed. TypeScript end to end, NestJS on the backend and Next.js on the frontend. | Layer | Choice | Notes | | --- | --- | --- | | Backend framework | NestJS | Owns the API, orchestrator, workflows, services, adapters, approvals, audit, and jobs. Its module/provider structure maps directly to the service architecture below. | | Frontend framework | Next.js (App Router, React) | Command center dashboard and product surfaces. Consumes the NestJS API; no business logic in the frontend. | | UI system | Tailwind CSS with shadcn/ui | Dense operational layouts, not marketing pages. | | Database | PostgreSQL | Workflow runs, approvals, audit logs, tasks, contact metadata, source-system mappings, and operational state. | | ORM | TypeORM | Native NestJS integration via `@nestjs/typeorm`; entities and repositories align with NestJS dependency injection. | | Orchestration (authoring) | flowkit (`@db-lyon/flowkit`) | Multi-step brokerage flows defined declaratively in YAML: reusable typed tasks composed into ordered and nested flows, conditional steps, and lifecycle hooks. This is the default home for multi-step logic. | | Durable execution and jobs | BullMQ | Runs flows as durable jobs: retries, backoff, delayed jobs for timers and deadlines, repeatable jobs for schedules, concurrency, and parent/child fan-out. flowkit defines the steps; BullMQ makes running them durable. | | Cache and queue broker | Redis | Backing store for BullMQ and application caching. | | Auth | Passport via `@nestjs/passport` | Role-based access control and tenant-aware permissions. Strategy-based, so SSO/SAML can be added for later SaaS tenancy without reworking the model. | | Storage | S3-compatible object storage | Uploaded contact files, generated reports, workflow exports, and document artifacts. The concrete provider follows the hosting decision in M0. | | Search | PostgreSQL full-text | No vector search until a workload actually needs it. | | AI provider | Anthropic Claude behind a thin internal interface | Claude is the default model. The interface keeps a model swap a config change, not a rewrite. | | Observability | Structured logs, job and workflow traces, error monitoring, business-readable audit views | Technical telemetry and the user-facing audit trail are separate concerns. | Python should not be used for this platform. The architecture, workflow runtime, agents, adapters, dashboard, scripts, and automation tooling are all TypeScript, on NestJS and Next.js. ### Orchestration model Orchestration is structured in three tiers. Each tier sits behind a clean seam so it can change without rewriting the tier below it. 1. **Task.** A unit of work, implemented as a typed flowkit task (`BaseTask`). Tasks own the actual work: read an adapter, classify an exception, draft a message. 2. **Flow.** A synchronous, in-process composition of tasks, defined declaratively in flowkit YAML. A flow runs to completion in one invocation. It does not pause for a human. Flows run as durable BullMQ jobs, so retries, backoff, scheduling, deadlines, and concurrency are handled outside the flow definition. Postgres holds run state and the audit trail. Flow definitions stay free of BullMQ specifics so the executor can change without rewriting flows. 3. **Journey.** A durable, stateful, long-lived process that spans many flow-runs over days or weeks: contract-to-close, agent onboarding, listing launch, partner handoff. The journey is a first-class persisted object, not an implicit pile of segments. It is modeled as an explicit state machine: named states, allowed transitions, the flow that runs on each transition, and per-state timers and deadlines. State and history live in Postgres; timers fire through BullMQ delayed and repeatable jobs; approvals, webhooks, and manual operator actions are normalized into journey events that drive transitions. The journey tier is what preserves the overarching process. A flow-run is a stateless transition that reads and writes journey state; segmentation at approval gates is the execution mechanism, not the model. The journey object is also the natural source for the dashboard's stuck-workflow and at-risk views, so it earns its place beyond orchestration. The journey tier is a flowkit upgrade, deliberately scoped to explicit state machines. APEX's journeys are few and well-defined, which is exactly the regime where a declarative state machine beats a general durable-execution engine: its transition log is business-readable for the audit trail, and explicit states migrate across deploys far more cleanly than in-flight replay histories. The platform will not build replay-based durable execution (linear code that survives restart by re-running and replaying recorded side-effects). That is the hard core of a dedicated engine and is not worth reimplementing. The genuinely hard parts the journey tier must own are per-journey concurrency (serialize a journey's events, for example by keying its BullMQ queue on journey id or using Postgres advisory locks) and exactly-once behavior across a crash mid-transition. The latter is handled by making flowkit tasks idempotent, which is required regardless of tier. None of the journey tier is needed for M0-M1. Those flows are short and read-first, so a flow per segment is sufficient. The seam is designed in now; the journey tier is built when the first genuinely multi-day live journey lands. **Possible future escalation to Temporal.** Temporal is open source (MIT) and self-hostable, so this is a use decision, not a build or license decision. It is deliberately not adopted now: M0-M3 needs are fully covered by flowkit plus BullMQ, the journey tier covers the finite set of brokerage lifecycles, and self-hosting Temporal carries real operational weight (its frontend, history, matching, and worker services plus a dedicated datastore) and a second programming model. The escalation trigger is specific: if a journey ever needs arbitrary durable control flow that a declarative state machine cannot express, or replay-grade exactly-once guarantees the state machine tier cannot meet, adopt self-hosted upstream Temporal for that journey class only and let it own those journeys. It is not reimplemented; the same clean seam that isolates the executor is what keeps that a contained decision. ## Service Architecture The application should be organized around explicit services rather than a monolithic agent: - `OrchestratorService`: classifies triggers, selects the flow to run, retrieves context, delegates work, enforces approval policy, and produces final status. - `WorkflowRunService`: runs flowkit flows as durable BullMQ jobs, persists step state and results through flowkit lifecycle hooks, handles retries, and exposes run history. - `JourneyService`: owns the journey tier. Persists journey state, validates transitions against each journey's state machine, runs the flow for a transition, schedules per-state timers and deadlines via BullMQ, and normalizes approvals, webhooks, and operator actions into journey events. Serializes events per journey and relies on idempotent tasks for exactly-once behavior. - `SkillRegistryService`: registers skill tasks with the flowkit task registry, validates tool access, and maps tasks to flows. - `ContextService`: retrieves approved APEX policies, data definitions, escalation rules, compliance requirements, and brand/marketing context. - `MemoryService`: separates policy memory, entity memory, workflow memory, and approved operational learning. - `IntegrationAdapterService`: centralizes external API access and enforces typed adapter contracts. - `ApprovalService`: manages approval queues, action tiers, role requirements, comments, rejections, and execution release. - `AuditLogService`: records workflow steps, tool calls, API responses, human actions, errors, retries, and final results. - `PermissionsService`: enforces role, tenant, object, and action-level permissions. - `DashboardStatusService`: translates workflow and source-system data into user-facing status cards. - `CRMService`: validates and wraps Twenty or another open-source CRM foundation. - `NotificationService`: sends internal notifications after permission and approval checks. ## Agentic Model The platform should follow practical agentic architecture patterns: use simple composable workflows first, then add autonomy where it improves outcomes. ### Orchestrator The orchestrator receives a user request, platform event, scheduled trigger, webhook, or integration signal. It should: - Classify the request or event. - Select the appropriate workflow. - Retrieve relevant context and source-system data. - Delegate bounded work to skills and subagents. - Enforce permissions and approval rules before execution. - Track every step in audit logs. - Retry, escalate, or send to manual review on failure. - Return a business-readable status summary to the dashboard. The orchestrator should not become an all-powerful agent with broad tools. It should be a controlled coordinator with narrow capabilities and explicit rules. ### Workflows Workflows are repeatable brokerage runbooks defined as flowkit flows in YAML and run as durable BullMQ jobs. Each flow declares triggers, inputs, ordered and nested steps, conditional branches, validation, approval gates, outputs, failure modes, and acceptance criteria. The flow YAML owns the sequencing; the work each step performs lives in typed flowkit tasks (see Skills). A single flow is bounded and synchronous; multi-day lifecycles that span many flow-runs are owned by the journey tier described in the orchestration model above, with flows acting as the per-transition work. Initial flow definitions: - `DailyOperationsReview.flow.yml` - `ContactImportAndCRMSetup.flow.yml` - `AgentOnboarding.flow.yml` - `NewListingLaunch.flow.yml` - `BuyerTransactionOpen.flow.yml` - `SellerTransactionOpen.flow.yml` - `ContractToClose.flow.yml` - `BrokermintFileManagement.flow.yml` - `MarketingCampaignLaunch.flow.yml` - `TradePartnerHandoff.flow.yml` ### Skills Skills are bounded capabilities implemented as typed flowkit tasks (extending `BaseTask`) and referenced from flows by `class_path`. Each task specifies purpose, allowed tools, required context, input schema, output schema, validation rules, approval requirements, and examples. Initial skill tasks: - `ImportAndDedupeContacts` - `SyncContactToTwenty` - `SyncContactToReChat` - `GenerateAgentOnboardingPlan` - `ReviewTransactionChecklist` - `CreateBrokermintFile` - `EscalateMissingComplianceItems` - `SummarizeDealStatus` - `LaunchListingMarketingKit` - `CreateXaraAssetRequest` - `PrepareAdWorksCampaign` ### Context Files Context files provide approved business knowledge. They should be versioned and reviewed before being used as policy memory. Initial context files: - `APEXBrandVoice.Context.md` - `OperationsPolicies.Context.md` - `TransactionComplianceRules.Context.md` - `AgentOnboardingStandards.Context.md` - `CRMDataDefinitions.Context.md` - `MarketingTemplates.Context.md` - `PartnerIntegrationRules.Context.md` - `BrokerageEscalationRules.Context.md` ### Subagents Subagents should be specialized workers with limited tools and clear boundaries: | Subagent | Primary Responsibility | Initial Tool Access | Restricted Actions | | --- | --- | --- | --- | | Operations Coordinator | Onboarding, recurring admin, internal task routing | Workflow status, task creation, onboarding checklist, internal notifications | Cannot approve compliance completion or send external messages without approval. | | Transaction Coordinator | Contract-to-close workflows, deadline tracking, Brokermint task routing | Transaction records, deadline checks, Brokermint read/status tools, task creation | Cannot mark critical transaction data complete without human approval. | | Compliance Reviewer | Missing fields, documents, checklist validation, escalation | Brokermint read-only, compliance rules, exception reporting | No write access to compliance status in v1. | | CRM Data Steward | Contact import, dedupe, enrichment, segmentation, CRM hygiene | CSV parser, duplicate detector, Twenty/ReChat preview, merge queue | Cannot bulk merge, delete, or sync externally without approval. | | Marketing Coordinator | Listing launch, Xara assets, AdWorks prep, marketing task status | Listing intake, Xara/AdWorks status, draft requests | Cannot launch paid campaigns or publish externally without approval. | | Partner Liaison | Title, warranty, mortgage, and partner handoff status | Limited partner status sync, partner task notifications | Cannot expose additional brokerage/client data without role-approved permission. | | Support Assistant | Dashboard help and workflow explanation | Read access to workflow history and help content | Cannot modify records or trigger external actions. | | Evaluator | Output review for higher-risk work | Read-only access to outputs, policy versions, and audit trails | Cannot execute business actions. | ## Automation Control Model APEX should classify actions into risk tiers: | Action Type | Examples | Default Control | | --- | --- | --- | | Read-only analysis | Summaries, checklist review, duplicate suggestions, status classification | Auto-run with audit log. | | Low-risk internal write | Create internal task, draft message, update workflow status | Auto-run with role permissions and audit log. | | External or customer-visible write | Send email/SMS, update partner status, sync approved CRM records | Human approval or narrow pre-approved rule. | | High-risk or irreversible action | Bulk merge/delete, mark compliance complete, change transaction-critical data | Explicit approval plus audit review. | Early milestones should emphasize read-only and low-risk internal writes. External writes should be rare and approval-controlled until the workflow has proven accurate in live APEX operations. ## Memory Strategy Memory must be explicit, scoped, and reviewable. - **Policy memory**: approved APEX rules, compliance requirements, escalation policies, and approval requirements. - **Entity memory**: contacts, listings, transactions, tasks, agents, partner handoffs, notes, and activity history stored in Postgres and/or the validated CRM foundation. - **Workflow memory**: workflow runs, retries, approvals, failures, corrections, and final outcomes. - **Operational learning memory**: recurring corrections from staff that become reusable only after human approval. The system should not silently turn one-off AI observations into durable rules. Operational learning needs an approval path, version history, and rollback mechanism. ## Audit Requirements Every workflow run should capture: - Trigger, user, role, tenant, entity, and timestamp. - Source systems queried and data versions used. - Context files, policy versions, and approval rules loaded. - Workflow steps, subagents, skills, tool calls, API responses, retries, and errors. - Human approvals, rejections, edits, comments, and timestamps. - Final result, unresolved exceptions, and next action owner. The dashboard should expose audit trails in business language. Technical logs are necessary for debugging, but APEX users need to understand what happened without reading raw model transcripts. ## Source-Of-Truth Model The platform should not claim to be the source of truth for every object on day one. It should map ownership by object type and expose source provenance in the dashboard. | Object / Status | Initial Source Of Truth | APEX Platform Role | | --- | --- | --- | | Contacts | Twenty or validated open-source CRM foundation, with ReChat coordination where needed | Normalize, dedupe, segment, task, sync, and expose status. | | Tasks and next actions | APEX workflow system, with optional sync to CRM/task tools | Own workflow-driven task status, owner, due date, and audit. | | Transaction files | Brokermint | Read status, detect missing items, create exception reports, queue approved actions. | | Transaction risk | APEX workflow system using Brokermint and policy context | Infer risk level, explain reason, show confidence and source data. | | Listing assets | Xara Cloud or current marketing asset system | Track request, approval, delivery, and source status. | | Campaign status | AdWorks or current marketing campaign system | Track prep, approval, launch status, and stale updates. | | Partner status | Partner systems or controlled partner update flow | Show limited status, handoff owner, data boundaries, and audit. | | Approvals | APEX workflow system | Own queue, role, decision, comment, and execution release. | | Audit trail | APEX workflow system | Own complete workflow-level audit across systems. | The dashboard should distinguish confirmed source data from inferred risk, stale data, manually corrected data, and pending approval. ## Integration Adapters Each external system should have a typed adapter with consistent behavior: - Authentication and credential storage. - Read/write capability map. - Rate limit handling. - Retry and backoff policy. - Webhook and polling support. - Error classification. - Source record mapping. - Conflict detection. - Audit logging. - Permission checks. - Test/sandbox strategy. Initial adapters: - Xara Cloud adapter. - ReChat adapter. - AdWorks adapter. - Brokermint adapter. - Twenty/open-source CRM adapter. - Email/SMS adapter. - Calendar/task adapter. - Partner API adapters for title, warranty, and mortgage providers. Milestone 0 must validate real API, webhook, sandbox, and export capabilities before dependent automation scope is finalized. ## CRM / Twenty Validation Twenty is the preferred open-source CRM foundation to validate, not an irreversible decision. The validation should answer: - Can Twenty support APEX contact fields, ownership rules, tags, segments, activity timelines, tasks, pipelines, and reporting needs? - Can it handle import, dedupe, sync, and conflict resolution at APEX volumes? - Can it integrate cleanly with ReChat and existing communication history where required? - Can APEX customize brokerage-specific objects without fighting the underlying model? - Can it support permission boundaries for agents, operations, leadership, and future tenants? - Should Twenty become the long-term system of record, a connected CRM layer, or a component replaced by a custom model? The CRM beta should not be treated as a full replacement until contact import, adoption, reporting, and sync reliability are proven with a pilot group. ## Dashboard Trust Requirements The dashboard must earn trust before it becomes the daily work surface. Each important status card should include: - Status label. - Source system. - Last sync time. - Owner. - Next action. - Risk level or priority. - Confirmed/inferred/stale/manual status. - Open exceptions. - Approval requirement if any. - Approval history. - Manual correction path. - Link to workflow run or audit detail. The first version should be exception-first, not a complete "single pane of glass." It should show what needs attention today: stuck workflows, missing items, approval requests, stale statuses, failed integrations, and clear owners. ## Workflow Artifact Packs Each production workflow should ship with an artifact pack: - Flow definition (flowkit YAML). - Task (skill) definitions. - Context dependencies. - Input and output schemas. - Approval policy. - Adapter capability map. - Test cases and fixture data. - Dashboard status card definition. - Audit event schema. - Failure and fallback plan. - Acceptance criteria. - Pilot feedback form. - Go/pivot/stop decision memo template. These packs make the system maintainable and transferable between the build team and APEX operations. ## Mermaid Visualization Appendix The full visualization appendix lives in `APEX-Architecture-Visualizations.md` in this same directory. That file is now sequence-chart focused so the technical plan can show how work, approvals, source data, and trust move through the platform over time rather than relying on abstract system maps. Relevant sequence charts include: - M0 discovery to M1 scope lock. - Daily operations review in "Today at APEX." - Controlled Brokermint exception review. - Approval queue and execution release. - Milestone decision gates. ## Milestone Implementation Plan ### Milestone 0: Discovery, Workflow Map, And Technical Validation Estimated timeline: 1-2 weeks. Technical outputs: - Workflow map for current APEX operations. - Source-system inventory. - API, webhook, sandbox, and export feasibility report. - Current automation inventory and keep/rebuild recommendation. - Data model draft for contacts, listings, transactions, tasks, approvals, workflow runs, and audit logs. - Source-of-truth map by object type. - Approval, memory, and audit policy draft. - CRM/Twenty validation criteria. - NestJS/Next.js architecture plan. - Dashboard wireframe for "Today at APEX." - Baseline metrics for the first pilot workflow. - Milestone 1 acceptance criteria. - Backlog and sequencing recommendation. Acceptance evidence: - APEX confirms the first operational workflow to pilot. - Required system access is known or blocked explicitly. - M1 scope is fixed enough to estimate and build. - Risky writes are excluded or approval-controlled. ### Milestone 1: Platform Foundation And Operations Command Center Estimated timeline: 3-5 weeks. Technical outputs: - NestJS API and Next.js application shell. - Auth, roles, and environment setup. - Postgres schema for workflow runs, approvals, audit logs, source mappings, and tasks. - flowkit and BullMQ orchestration wired together, with run state and audit persisted to Postgres. - Orchestrator skeleton with typed flow routing. - Approval queue, including the segment-and-resume pattern for gated flows. - Audit log service. - Initial integration adapter pattern with at least one real or stubbed source. - "Today at APEX" command center showing sample workflow status, approvals, exceptions, owners, and audit detail. - One flowkit flow running end to end as a durable job in a controlled environment. Acceptance evidence: - Operations can use the command center to review real or representative exceptions. - Users can see source, status, owner, approval requirement, and audit detail. - The system can run one workflow, record steps, queue approvals, and show outcome. - The team can decide whether to continue into live workflow pilots. ### Milestone 2: Contact Import And CRM Setup Pilot Estimated timeline: 3-5 weeks. Technical outputs: - Contact upload flow. - Parsing, normalization, and validation. - Duplicate detection and merge suggestion queue. - Segmentation and initial follow-up task generation. - Twenty/ReChat sync preview through adapters. - Human approval before merges or external sync. - Import summary and audit trail. Acceptance evidence: - A real or representative contact list can be processed. - Duplicate suggestions are understandable and reviewable. - Approved contacts can be prepared for CRM sync. - Exceptions are visible and assigned. ### Milestone 3: Agent Onboarding Workflow Estimated timeline: 3-5 weeks. Technical outputs: - Agent onboarding workflow. - Checklist and task generation. - Tool setup status tracking. - Contact import handoff. - Missing-item reminders. - Operations and agent-facing status. - Approval rules for any external system changes. Acceptance evidence: - A new agent can be onboarded through a visible workflow. - Operations can see blockers and next owners. - Agents understand what is complete, pending, and required. ### Milestone 4: Brokermint File Management Pilot Estimated timeline: 4-6 weeks. Technical outputs: - Brokermint read adapter validation. - Daily or scheduled file review workflow. - Checklist and required-item validation. - Exception report by risk, owner, file, and due date. - Escalation rules. - Audit trail and dashboard status. Acceptance evidence: - Operations can review missing items and at-risk files faster than the current process. - The system does not mark compliance complete without approval. - Brokermint access limitations are documented and handled. ### Milestone 5: Marketing Launch Workflow Estimated timeline: 3-5 weeks. Technical outputs: - Listing intake workflow. - Xara asset request/status adapter where feasible. - AdWorks campaign prep/status adapter where feasible. - Approval routing for Taylor, leadership, or agent review as needed. - Marketing status cards for listing launch. - Draft, route, approve, and track behavior before live publishing. Acceptance evidence: - A listing launch can be tracked from intake through approval. - Marketing can see blocked work, pending approvals, and channel status. - Paid campaign launch remains approval-controlled. ### Milestone 6: Agent Dashboard MVP Estimated timeline: 6-8 weeks. Technical outputs: - Agent home view. - Tasks, contacts, active deals, listings, workflow status, alerts, stale statuses, and next-best actions. - Contact detail view. - Transaction/listing status view. - Notification center. - Basic CRM actions. - Trust details on important statuses. Acceptance evidence: - A pilot group can use the dashboard for daily status review. - Dashboard usage reduces status questions, tool switching, or manual follow-up. - Agent feedback identifies the minimum feature set for broader rollout. ### Milestone 7: CRM Foundation / Twenty Validation Beta Estimated timeline: 8-12 weeks. Technical outputs: - Twenty validation environment. - APEX contact fields, tags, segments, ownership rules, activity timeline, tasks, pipelines, imports, exports, and reporting. - Sync framework with ReChat or other systems where required. - Admin visibility controls. - Pilot agent contact management. Acceptance evidence: - A subset of agents can manage real contacts. - Import/sync behavior is reliable enough for a broader pilot. - APEX can decide whether Twenty should become the long-term system of record. ### Milestone 8: Conditional Partner Integration Pilot Estimated timeline: 6-10 weeks. Entry condition: - Internal workflows show measurable ROI and trusted status behavior. Technical outputs: - Partner handoff workflow. - Limited partner status cards. - Partner data boundary rules. - One trusted partner pilot. - Audit trail for partner-visible updates. Acceptance evidence: - Partner visibility improves internal status without exposing unnecessary data. - APEX can decide whether partner access belongs in the product roadmap or remains an internal advantage. ### Milestone 9: Conditional SaaS Readiness And External Brokerage Pilot Estimated timeline: 8-12 weeks. Entry condition: - APEX has internal proof, active usage, support capacity, and a clear target customer. Technical outputs: - Tenant isolation. - Brokerage configuration. - Branding settings. - Role and permission templates. - Tenant onboarding flow. - Support/admin console. - Usage analytics. - External pilot environment. Acceptance evidence: - A second brokerage or test tenant can be configured without custom engineering. - Setup time, support load, usage, and product-market signals are measurable. ## Cost Planning Ranges These ranges are planning estimates and should be refined after Milestone 0 validation. | Workstream | Estimated Cost | | --- | ---: | | M0: Discovery sprint and workflow map | $8,000-$18,000 | | M1: Platform foundation and operations command center | $20,000-$42,000 | | M2: Contact import and CRM setup pilot | $20,000-$45,000 | | M3: Agent onboarding workflow | $20,000-$45,000 | | M4: Brokermint file management pilot | $25,000-$60,000 | | M5: Marketing launch workflow | $20,000-$50,000 | | M6: Agent dashboard MVP | $50,000-$100,000 | | M7: CRM foundation / Twenty validation beta | $70,000-$150,000 | | M8: Conditional partner integration pilot | $40,000-$100,000 | | M9: Conditional SaaS readiness and external brokerage pilot | $75,000-$175,000 | Phase view: | Phase | Milestones | Goal | Estimated Cost | | --- | --- | --- | ---: | | Phase 1 | M0-M1 | Discovery, architecture, command center, trust foundation | $28,000-$60,000 | | Phase 2 | M2-M3 | Contact import and agent onboarding pilots | $40,000-$90,000 | | Phase 3 | M4-M6 | Brokermint, marketing workflow, and agent dashboard MVP | $95,000-$210,000 | | Phase 4 | M7-M8 | CRM foundation validation and conditional partner integration | $110,000-$250,000 | | Phase 5 | M9 | Conditional SaaS readiness and external brokerage pilot | $75,000-$175,000 | ## Build Team And Handoff Model Recommended delivery roles: - Product lead: scope, milestone acceptance, staff feedback, and go/pivot/stop decision memos. - Engineering lead: architecture, technical tradeoffs, security, deployment, code quality, and handoff. - Backend/workflow engineer: orchestrator, workflows, jobs, adapters, approvals, and audit logs. - Frontend/product engineer: command center, dashboard, CRM views, status cards, and approval UX. - Integration/DevOps support: API testing, environments, webhook/polling strategy, monitoring, and vendor constraints. - QA/operations reviewer: acceptance tests, pilot feedback, workflow verification, and regression checks. Approximate staffing: - M0-M3: 3-4 people with some part-time roles. - M4-M6: 4-6 people as integrations, dashboard UX, and workflow QA run in parallel. - M7-M9: 5-7 people if CRM validation, partner integration, and SaaS hardening overlap. Handoff requirements: - Architecture decision records. - Environment and deployment documentation. - Adapter capability documentation. - Workflow artifact packs. - Test fixtures and acceptance criteria. - Admin/user operating guide. - Support and escalation runbook. - Credential ownership and rotation plan. - Backlog with milestone gates. ## Success Metrics Internal metrics: - Hours saved per week for operations. - Time to onboard a new agent. - Percentage of imported contacts successfully normalized, deduped, and segmented. - Reduction in missing transaction items. - Reduction in duplicate data entry. - Time from listing creation to marketing launch readiness. - Reduction in status-request messages. - Time to resolve missing items, stuck workflows, and approvals. - Percentage of important statuses with source, last sync, owner, and next action visible. - Workflow success rate. - Manual intervention rate. - Dashboard weekly active usage for pilot users. Avoid treating time-in-app as the primary success metric. A strong command center may reduce time spent searching for status. Commercial metrics should be considered only after internal proof: - Pilot brokerage setup time. - Support tickets per brokerage. - Monthly recurring revenue. - Gross margin after AI and infrastructure usage. - Retention and expansion. ## Risks And Controls | Risk | Control | | --- | --- | | API access is weaker than expected | Validate API, webhook, sandbox, and export capability in M0 before dependent scope is committed. | | AI recommendations are inaccurate | Use deterministic workflow guards, structured outputs, evaluator checks, confidence thresholds, and human approval. | | Staff do not trust dashboard status | Show source system, last sync time, confirmed/inferred/stale labels, approval history, and correction paths. | | Compliance exposure | Keep compliance completion and transaction-critical changes behind explicit approval and audit logs. | | CRM source-of-truth confusion | Decide ownership by object type and use adapter-level conflict handling. | | Scope expands before value is proven | Fund by milestone and require acceptance evidence at each gate. | | Partner or SaaS work starts too early | Require measurable internal ROI and active usage before external packaging. | | Partner access exposes too much data | Start with one trusted partner, limited views, field-level restrictions, role permissions, and audit trails. | | Integration failures create false confidence | Mark degraded integrations clearly, keep last-known status labeled stale, and escalate unresolved sync failures. | ## Open Technical Decisions 1. Which workflow should be the first live pilot after the command center foundation: contact import, onboarding, Brokermint exceptions, or marketing launch? 2. Which systems provide sufficient API, webhook, sandbox, or export access for M1-M2? 3. Which object types should Twenty own if validation succeeds? 4. How should ReChat coordinate with Twenty during the CRM transition? 5. Which actions are prohibited, approval-only, or safe to automate? 6. What compliance, document retention, and brokerage audit requirements must be encoded? 7. What baseline metrics will be captured before automation starts? 8. Who owns API credentials, vendor relationships, QA acceptance, and milestone signoff? 9. Should multi-tenancy be designed into the foundation immediately as a low-level constraint, or deferred until M9 hardening? 10. What support model is required if the product becomes external-facing? ## Recommended Technical Next Step Approve M0-M1 as the first technical commitment. M0 should produce the workflow map, feasibility report, architecture plan, source-of-truth map, dashboard wireframe, approval/audit policy, CRM validation criteria, and fixed M1 scope. M1 should build the NestJS/Next.js foundation, command center, workflow/audit/approval core, and one controlled sample workflow. Do not start broad CRM replacement, partner integration, or SaaS hardening until the command center proves that APEX staff trust the status layer and that at least one workflow reduces real operational friction.