Section 01 -- Overview [M]
| Field | Value |
|---|---|
| Use Case ID | UC-D2 |
| Client Reference [M] | Internal demo / reference implementation |
| System Name [M] | ARC Collective |
| Domain [M] | CRM / Lead Management / Finance Reconciliation |
| One-Line Description [M] | AI-scored email leads and bank-invoice reconciliation orchestrated by Nexus pipelines, rendered via ChameleonV2 |
| Status [M] | In Development -- Phase 2 (nodes implemented, integration pending) |
| Target Delivery [M] | Q3 2026 (demo-complete) |
Summary [M]
ARC Collective is a fictional freelance CRM business with two operational domains: RevOps (email lead scoring and offer drafting) and Finance Ops (bank CSV transaction matching against open invoices).
ARC has no separate codebase. The Nexus node executors in wormwood-engine ARE the ARC logic. The use case demonstrates the full Nexus value proposition: a customer builds pipelines in the canvas, seeds entity classes, and ChameleonV2 renders a complete CRM application from those pipelines -- with no frontend code changes required when pipelines change.
The application is served via NEXUS_APP.html -- a generic pipeline-driven React SPA that handles any org. ARC is one org among many.
Section 02 -- Actors [M]
| Role [M] | Description [M] | Access Level [D] | Frequency [D] |
|---|---|---|---|
| Owner | Freelancer / agency owner. Manages leads, drafts offers, reconciles invoices. Full system access. | Admin -- all pipelines, all entities, all views | Daily |
| Finance | Bookkeeper. Uploads bank CSVs, resolves unmatched transactions, generates tax reports. | Finance pipelines only -- invoice, reconciliation, reports | Weekly |
| Prospect | External. Sends emails that become leads. Never logs into system. | None -- inbound only | Continuous |
Section 03 -- User Stories [M/D]
Actor: Owner
- P1 [M]: As Owner, I want inbound emails scored for sentiment and urgency, so that I respond to hot leads first.
- P1 [M]: As Owner, I want a dashboard showing all leads with score and tier badges, so that I see my pipeline at a glance.
- P1 [M]: As Owner, I want to create a project offer from a brief, have AI draft the text, and approve/revise before sending, so that offers are consistent and fast.
- P2 [D]: As Owner, I want to assign leads to team members from the list view, so that work is distributed.
- P2 [D]: As Owner, I want PDF export of approved offers, so that clients receive a professional document.
Actor: Finance
- P1 [M]: As Finance, I want to upload a bank CSV and have transactions matched to open invoices by reference and amount, so that reconciliation is automated.
- P1 [M]: As Finance, I want unmatched transactions flagged for review with clear reasons, so that I only handle exceptions.
- P2 [D]: As Finance, I want to mark unmatched transactions as resolved or ignored with notes, so that the audit trail is complete.
- P3 [D]: As Finance, I want a monthly/annual tax report generated from reconciled payments, so that Polish tax filing is streamlined.
Section 04 -- System Flows [M/D]
Flow: Email Lead Scoring [M]
Trigger [M]: New email arrives in monitored inbox (scheduled poll every 15 minutes).
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Poll inbox | System | Gmail OAuth credentials, last_synced_at | Raw email batch (from, subject, body, thread_id) | -- |
| 2 | Classify email | System | Email text | sentiment (positive/neutral/negative), urgency (high/medium/low), intent | -- |
| 3 | Score lead | System | Classification result + scoring rules | lead_score (0-100), lead_tier (hot/warm/cold) | -- |
| 4 | Deduplicate | System | thread_id | Accept or skip (same thread = update, not duplicate) | If duplicate: update existing entity |
| 5 | Store | System | Scored lead entity | ProspectLead record | -- |
| 6 | Route by tier | System | lead_tier | Hot -> CRM priority queue; Cold -> archive | If hot: notify Owner immediately |
Result [M]: ProspectLead entity stored with score. Hot leads surfaced on Owner dashboard.
Exceptions [D]: Gmail OAuth failure -> retry with exponential backoff. AI classification failure -> store lead with sentiment=neutral, urgency=low (safe default, flagged for review).
SLA [D]: Email -> scored lead: under 60 seconds per message batch.
Volume [M]: 10-50 emails per day. Batch of up to 50 per poll cycle.
Flow: Offer Drafting [M]
Trigger [M]: Owner clicks "New Offer" in navigation.
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Fill project brief | Owner | client_name, project_title, brief_text, budget, deadline | Form submission | -- |
| 2 | AI drafts offer | System | Brief text + prompt template | offer_text (Polish/English) | -- |
| 3 | Review offer | Owner | AI-drafted text + original brief side-by-side | APPROVE or REVISE | If REVISE: return to step 2 with Owner's edits |
| 4 | Store approved offer | System | Approved offer entity | Offer record with status=approved | -- |
| 5 | Generate PDF | System | Offer text + template | PDF file | -- |
Result [M]: Approved offer stored, PDF generated, ready to send.
Exceptions [D]: AI unavailable -> display error, allow manual text entry. PDF generation failure -> offer still stored, PDF can be retried.
SLA [D]: Brief submission -> AI draft presented: under 15 seconds.
Volume [M]: 5-15 offers per week.
Flow: Bank CSV Reconciliation [M]
Trigger [M]: Finance uploads a bank CSV export file.
| # | Step [M] | Actor [M] | Input [M] | Output [D] | Decision [M] |
|---|---|---|---|---|---|
| 1 | Upload CSV | Finance | CSV file (Wise/PKO/mBank format) | Parsed transaction rows | -- |
| 2 | Normalise currency | System | Transaction rows with mixed currencies | All amounts normalised to PLN | -- |
| 3 | Match to invoices | System | Transactions + open invoices | Matched pairs (within tolerance), unmatched remainder | Tolerance: 1% amount variance |
| 4 | Store matched | System | Invoice-transaction pairs | ReconciledPayment records, invoice status -> paid | -- |
| 5 | Flag unmatched | System | Transactions with no invoice match | UnmatchedTransaction records with reason | -- |
| 6 | Alert finance | System | Unmatched count | Email notification to finance | If unmatched > 0: send alert |
Result [M]: Matched invoices marked paid. Unmatched transactions flagged for manual review.
Exceptions [D]: CSV parse failure -> reject file with error message (malformed header, unsupported format). Zero matches -> all transactions flagged, finance alerted.
SLA [D]: CSV upload -> reconciliation complete: under 30 seconds for 500 rows.
Volume [M]: 1-4 CSV uploads per week. 50-500 transactions per file.
Section 05 -- Data Model [M/D]
Entities
| Entity [M] | Description [M] | Key Fields [M] | States [D] | Relationships [D] |
|---|---|---|---|---|
| ProspectLead | Inbound email lead scored by AI | from_email, subject, lead_score, lead_tier | new -> contacted -> converted / archived | Derived from EmailEntity |
| EmailEntity | Raw inbound email record | from_email, subject, body, thread_id | ingested -> classified -> scored | Source for ProspectLead |
| OpenInvoice | Unpaid invoice awaiting reconciliation | invoice_number, client_name, total_amount, currency, due_date | unpaid -> partial -> paid / overdue / disputed | Target of MatchNode |
| BankTransaction | Single row from bank CSV export | date, amount, currency, reference, counterparty | imported -> matched / unmatched | Input to MatchNode |
| ReconciledPayment | Matched invoice-transaction pair | invoice_number, transaction_reference, amount, match_confidence | reconciled (immutable audit record) | Links OpenInvoice + BankTransaction |
| UnmatchedTransaction | Transaction with no invoice match | date, amount, reason, status | pending_review -> resolved / ignored / disputed | Derived from BankTransaction |
| Offer | Project brief + AI-drafted offer | client_name, project_title, brief_text, offer_text, status | draft -> pending_approval -> approved / rejected | Created by Owner |
Business Rules [M/D]
| ID | Rule [M] | Trigger [D] | On Violation [D] |
|---|---|---|---|
| BR-01 | Lead score is calculated from 5 weighted rules: sentiment.eq.positive(30), urgency.eq.high(20), company_size.gte.100(25), domain.not_null(15), score_hint.gte.70(10) | LeadScoreNode execution | Score defaults to 0 if input fields missing |
| BR-02 | Hot threshold = score >= 70. Warm = 40-69. Cold = below 40. | After scoring | Tier assigned deterministically |
| BR-03 | Invoice match tolerance: transaction amount within 1% of invoice total | MatchNode execution | Outside tolerance = unmatched |
| BR-04 | Deduplication: same thread_id within 24h = update existing lead, not new record | EmailIngest output | Duplicate suppressed, existing entity updated |
| BR-05 | Offer requires approval before PDF generation | ApprovalGate node | Draft offers cannot generate PDF |
Section 06 -- Screens [D]
| Screen [D] | Actor [M] | Purpose [D] | Key Elements [D] |
|---|---|---|---|
| Leads Dashboard | Owner | Overview of all scored leads with tier badges | DashboardNode metrics (total, hot count, avg score) + ListViewNode (lead table with row actions) |
| Invoices Dashboard | Owner, Finance | Outstanding and reconciled invoices | DashboardNode metrics (unpaid total, overdue count) + 2x ListViewNode (open + unmatched) |
| New Lead Form | Owner | Manual lead entry (override for non-email leads) | FormNode -> LeadScoreNode -> StoreNode |
| New Invoice Form | Finance | Create open invoice for future matching | FormNode -> StoreNode |
| New Offer Form | Owner | Project brief submission triggering AI offer draft | FormNode -> AITransform -> ApprovalGate -> StoreNode -> PdfGenerator |
| Lead Detail | Owner | View single lead (readonly) | FormNode (layout=detail, readonly=true) |
| Assign Lead | Owner | Assign lead to team member | FormNode (assignment fields) -> StoreNode |
| Resolve Unmatched | Finance | Mark unmatched transaction resolved with notes | FormNode (resolution fields) -> StoreNode |
| Clients | Owner | Client registry with contact details and project history | DashboardNode metrics (total clients, active) + ListViewNode (client cards with row actions). Source: frontend/src/app/clients/page.tsx#L19-L120, frontend/src/app/clients/[id]/page.tsx (detail: 4 tabs -- overview, projects, emails, configuration). REQ-CLI-01 |
| Projects | Owner | Project cards with 9-status lifecycle, tab filters, action feed | DashboardNode metrics (active, completed, on hold) + ListViewNode (project list with status badges and status filter pills). Source: frontend/src/app/projects/page.tsx#L34-L44 (9 statuses), frontend/src/app/projects/[id]/page.tsx (detail: 6 tabs -- overview, actions, emails, offers, invoices, timeline). REQ-PRJ-01 to 03 |
| Emails | Owner | Gmail thread list with sentiment badges, sync and calendar parse buttons | ListViewNode (email thread list with direction badges, sentiment, client assignment). Source: frontend/src/app/emails/page.tsx#L22-L230, frontend/src/app/emails/[id]/page.tsx (thread view + AI reply generator). REQ-EML-01 to 03 |
| Calendar | Owner | FullCalendar.js weekly/monthly view with Google sync and AI email-to-calendar parsing | DashboardNode (event counts) + CalendarView component (FullCalendar). Source: frontend/src/app/calendar/page.tsx#L16-L18 (dynamic import), frontend/src/components/CalendarView.tsx. Google sync + Parse from emails buttons. REQ-CAL-01, REQ-CAL-02 |
| Offers | Owner | Tabular offer list with status badges, linked to project. AI step suggestion. | ListViewNode (offer cards: title, steps count, total amount, status). Source: frontend/src/app/offers/page.tsx#L22-L250, frontend/src/app/offers/new/page.tsx (step editor + AI suggest). REQ-OFR-01 to 03 |
| Settings | Owner | Language, Google OAuth, API keys, backfill, AI prompt editor | FormNode (settings sections: Language, Google Integration, Backfill, Agent Prompts, API Keys). Source: frontend/src/app/settings/page.tsx#L14-L200, frontend/src/app/settings/prompts/page.tsx, frontend/src/app/settings/backfill/page.tsx. REQ-AGT-03, REQ-BKF-01 |
Rendering model: NEXUS_APP.html contains a view dispatcher (renderView()) that routes pipeline outputs to component renderers based on node types: DashboardNode (KPI metric cards), ListViewNode (sortable data tables with row actions), and FormNode (editable forms with submit). Each screen above maps to a seeded pipeline in scripts/seed_arc_pipeline.py. The renderers are generic -- the same ListViewNode renderer handles Leads, Clients, Projects, Invoices, Offers, Calendar, and Bank views by consuming different column/row configurations from pipeline output.
Source authority (AS -1): Screen definitions are derived from actual ARC source code at E:/repos/arc/frontend/src/app/ (21 page routes). View layouts, data contracts, and interactions are documented with source file:line references in NEXUS_ARC_REQUIREMENTS.html v2.0. The live ARC app at dev.arc.ou-uv.com is the visual reference for pixel-level fidelity.
Evidence chain: E:/repos/arc source (AS -1) → NEXUS_ARC_REQUIREMENTS.html (REQ-*) → This table (screen mapping) → scripts/seed_arc_pipeline.py (pipeline graphs) → NEXUS_APP.html renderers (view output).
Section 07 -- Integrations [M]
| System [M] | Direction [M] | Data [M] | Format [D] | Frequency [M] | Fallback [D] |
|---|---|---|---|---|---|
| Gmail (OAuth) | In | Inbound emails (from, subject, body, thread_id) | Gmail API JSON | Every 15 min (scheduler) | Queue missed polls, catch up on next cycle |
| Bank CSV (Wise/PKO/mBank) | In | Transaction rows (date, amount, reference, counterparty) | CSV file upload | Weekly manual upload | Reject malformed CSV with parse error |
| Anthropic Claude API | In/Out | Brief text -> offer text generation | REST JSON | On-demand (per offer) | Allow manual text entry if API unavailable |
| deltaPrism (graph store) | Out | All entity writes | HTTP JSON (deltaPrism API at :15000) | Per pipeline execution | Retry 3x, then fail pipeline with error |
| SMTP (email alerts) | Out | Unmatched transaction notifications | Per reconciliation run (if unmatched > 0) | Log alert, do not block pipeline |
Section 08 -- Infrastructure [D]
| Layer | Choice [D] | Reason [D] |
|---|---|---|
| Hosting | Docker (local dev), AWS Lambda (production option) | Pipeline-per-invocation model fits Lambda. Local Docker for development. |
| Database | PostgreSQL (pipeline metadata) + deltaPrism (entity storage) | PostgreSQL for admin/pipelines. deltaPrism for graph-native entity storage. |
| Frontend | NEXUS_APP.html (React SPA, ChameleonV2 components, ESM import map) | Generic pipeline-driven SPA. No ARC-specific frontend. |
| Runtime | Wormwood Local Python runtime | Standard Nexus execution engine |
| AI | Anthropic Claude 3.5 Sonnet (offer drafting, sentiment) | Best quality/cost for text generation tasks |
Constraints [M]
- Demo environment: no data residency requirements.
- Gmail OAuth requires GCP project credentials configured.
- Claude API requires ANTHROPIC_API_KEY environment variable.
- deltaPrism must be running at configured port for real entity storage.
Environments [D]
| Environment | Purpose |
|---|---|
| Development | Local Docker, demo_mode=True (no real external APIs) |
| Integration | Local Docker, real Gmail OAuth, real deltaPrism, Claude API |
| Demo | Deployed instance for stakeholder presentations |
Section 09 -- Critical Path [D]
| # | Item [D] | Depends On | Duration [D] | Blocker Risk [D] |
|---|---|---|---|---|
| 1 | NEXUS_APP.html form submission fix (execute endpoint) | -- | S (done) | None -- already resolved |
| 2 | Seed missing action pipelines (arc-view-lead, arc-assign-lead, arc-resolve-unmatched, arc-ignore-transaction) | -- | S | None |
| 3 | FormNode chameleon_schema output in execute response | #1 | S | None |
| 4 | ChameleonV2 Phase 1 (file reference, entity link, validation) | -- | L (external) | ChameleonV2 roadmap dependency |
| 5 | arc-offer pipeline seed + Offer entity class integration | #3 | M | ANTHROPIC_API_KEY required |
| 6 | Gmail OAuth real mode (GmailIngestExecutor) | GCP credentials | M | OAuth token refresh complexity |
| 7 | FieldMapper currency normalisation (PLN) | -- | M | Exchange rate data source |
| 8 | ReportGenerator Polish tax report | #7 | L | Tax format specification |
| 9 | StoreNode real deltaPrism write mode | deltaPrism running | M | Schema migration needed |
Parallel Work (off critical path) [D]
| Item | Can Start After | Duration |
|---|---|---|
| Entity class expansion (EmailEntity already done) | Anytime | S |
| Dashboard styling / theme alignment | Anytime | S |
| Locust load testing | #9 complete | M |
Milestones [D]
| Milestone | Reached When | Target Date |
|---|---|---|
| M1: Demo-complete (demo_mode) | All 6 seeded pipelines render correctly in NEXUS_APP.html. Forms submit via /execute. Row actions work. | Q2 2026 |
| M2: Offer pipeline live | arc-offer seeded, AI draft works with real Claude, approval gate functional | Q3 2026 |
| M3: Real integrations | Gmail OAuth live, deltaPrism writes, CSV from real files | Q3 2026 |
| M4: Finance complete | Currency normalisation, tax reporting, full reconciliation without demo_mode | Q4 2026 |
Section 10 -- What Is Needed [M]
| # | Item [M] | From [M] | Blocking [M] | Status [M] |
|---|---|---|---|---|
| 1 | ANTHROPIC_API_KEY configured in environment | DevOps | Yes -- blocks arc-offer AI drafting | Open |
| 2 | GCP OAuth credentials (Gmail API) | GCP project gmailshadow-489609 | Yes -- blocks real email ingest | Received (GMailShadow project) |
| 3 | deltaPrism instance running at configured port | Infrastructure | Yes -- blocks real entity storage | Available locally |
| 4 | ChameleonV2 Phase 1 delivery (validation + file inputs) | ChameleonV2 repo | No -- ARC works without it (basic forms sufficient) | Not started |
| 5 | Exchange rate data source for PLN normalisation | TBD (NBP API or static rates) | Yes -- blocks real currency conversion | Open |
| 6 | Polish tax report format specification | Finance domain knowledge | Yes -- blocks ReportGenerator | Open |
Section 11 -- Acceptance Criteria [M/D]
Definition of Done [D]
| Criterion [D] | Verified By [D] |
|---|---|
| All 10 pipelines seeded and executable (6 existing + 4 action pipelines) | seed_arc_pipeline.py runs without error, each pipeline returns valid node_outputs |
| Form submission calls /execute and stores entities | test_arc_complete.py passes |
| Lead scoring produces correct tier from test data | test_arc_pipeline.py LeadScoreNode assertions |
| Bank reconciliation matches within 1% tolerance | test_arc_pipeline.py MatchNode assertions |
| Row actions route to correct detail/action pipelines | NEXUS_APP.html manual test |
| Offer pipeline produces AI draft and presents approval gate | Manual test with real Claude API |
| No silent error swallowing in SPA | Code review (no catch blocks returning fallback data) |
Success Metrics (30/60/90 days) [M]
| Metric [M] | Target [M] | Measured By [D] |
|---|---|---|
| Pipeline execution success rate (demo mode) | 100% -- all seeded pipelines execute without error | Automated test suite |
| Lead scoring accuracy (against labelled test set) | 80%+ tier assignment matches human labelling | Test fixture comparison |
| Reconciliation match rate (test CSV) | 95%+ correct matches on known test data | test_arc_pipeline MatchNode test |
| Offer draft acceptance rate | 70%+ approved without revision (when Claude API live) | Manual tracking |
Section 12 -- Risks [D]
| # | Risk [D] | Likelihood [D] | Impact [D] | Mitigation [D] |
|---|---|---|---|---|
| R1 | Claude API cost overrun from offer drafting | L | M | Rate limit: max 20 offers/day. Monitor token usage. |
| R2 | Gmail OAuth token expiry during unattended operation | M | H | Token refresh logic in GmailIngestExecutor. Alert on auth failure. |
| R3 | deltaPrism schema migration breaks existing entities | L | H | Version entity schemas. Run migration scripts in test first. |
| R4 | Bank CSV format changes (Wise/PKO update export layout) | M | M | FieldMapper config per bank. Add new format parsers as CSV variants appear. |
| R5 | ChameleonV2 Phase 1 delay blocks advanced form features | M | L | ARC works with basic form types. Advanced fields are P2 enhancement. |
Open Questions [M]
| # | Question [M] | Impacts [D] | Resolution [M] |
|---|---|---|---|
| Q1 | What exchange rate source for PLN normalisation? (NBP API, ECB, static monthly?) | Flow: Bank CSV Reconciliation step 2 | Must be decided before real reconciliation |
| Q2 | Polish tax report format: JPK_VAT, or simplified ledger? | ReportGenerator template | Must be specified by Finance domain |
| Q3 | Should cold leads be stored at all, or discarded? | Storage volume, entity lifecycle | Currently stored. Confirm or change. |
Section 13 -- Cooperator Brief [D]
| Field | Value |
|---|---|
| Scope [D] | CRM pipeline system: email ingestion, AI scoring, offer drafting, bank reconciliation. 10 pipelines, 7 entity classes, 1 generic SPA. Full functional spec: NEXUS_ARC_REQUIREMENTS.html (9 modules, FUNC-CLI/PRJ/CAL, US-SET). |
| Stack [D] | Python (wormwood-engine), FastAPI, PostgreSQL (admin), deltaPrism (entities), React/ChameleonV2 (frontend via NEXUS_APP.html), Claude API (AI), Gmail API (ingest) |
| Key Files [D] | wormwood/arc/entity_classes.py, scripts/seed_arc_pipeline.py, wormwood/core/node_executors/, docs/NEXUS_APP.html |
| Architecture [D] | Pipeline-driven. Every screen is a pipeline output. NavMenuNode defines navigation. DashboardNode/ListViewNode define views. FormNode defines data entry. No bespoke UI code per feature. |
| Node Executors Used [D] | GmailIngest, AiTransform, LeadScoreNode, MatchNode, ConditionBranch, StoreNode, FormNode, DashboardNode, ListViewNode, NavMenuNode, EmailForward, BankCsvIngest, FieldMapper, ReportGenerator, PdfGenerator, HumanGateNode |
| Tests [D] | tests/test_arc_pipeline.py, tests/test_arc_ui_nodes.py, tests/test_arc_complete.py, tests/test_arc_e2e.py |
| Current Gaps [D] | arc-offer pipeline not seeded. Row action pipelines not seeded. Real Gmail/deltaPrism/Claude integrations in demo_mode only. Currency normalisation not implemented. Tax reporting not implemented. |
| Roadmap Reference [D] | docs/ARC_BUILD_PLAN.md (M-ARC-P8 through P13). M-ARC-P10 (ARC_APP.html) SUPERSEDED -- use NEXUS_APP.html. |
Version History
| Version | Date | Changes |
|---|---|---|
| UC-D2-ARC-v2.0 | 2026-05-02 | Rewritten to UCT-3.1 format. Incorporates ARC_REQUIREMENTS.md and ARC_BUILD_PLAN.md findings. Reflects NEXUS_APP.html as canonical SPA (ARC_APP.html deleted). |
| UC-D2-ARC-v1.0 | 2026-04-25 | Original use case HTML (pre-template format). |