App Flow & Information Architecture

How every module of Hrunit CRM connects — the end-to-end funnel, the navigation map, what each role sees, and the cross-cutting UX — so a designer or developer can hold the whole app in their head. This is the frontend/UX companion to the roadmap.

Hrunit CRM is a single-tenant B2B sales-acquisition automation platform. It runs one funnel end to end — Research → Campaign assignment → Outreach → Connect → Closing — automating the high-volume work and leaving people only the phone calls and the deal close. One data model, one Benchmark score, one lifecycle state machine thread the whole thing together.

1. The funnel, end to end

Every stage consumes the output of the previous one and writes state back onto the Target (the prospect company — never "Lead"). The Benchmark score is computed once during Research and then flows through every downstream stage as the universal sort key.

flowchart LR
    subgraph RES["1 · Research"]
        R1[ResearchJob<br/>postal code + industry] --> R2[Serper.dev Maps<br/>+ enrichment sources]
        R2 --> R3[Benchmark scoring<br/>0-100, 5 dimensions]
    end

    subgraph CAMP["2 · Campaign assignment"]
        C1[AssignmentRule<br/>threshold OR llm_prompt]
    end

    subgraph OUT["3 · Outreach"]
        O1[3-mail sequence] --> O2[VirtualCompany /<br/>VirtualEmployee senders]
        O2 --> O3[Bandit picks StepVersion<br/>Thompson Sampling]
        O3 --> O4[reply processing]
    end

    subgraph CON["4 · Connect"]
        N1[Shifts + call Packages<br/>top-N by benchmark] --> N2[Live cockpit<br/>CloudTalk power dialer]
        N2 --> N3[disposition + KPIs]
    end

    subgraph CLO["5 · Closing"]
        L1[Round-robin pipeline] --> L2[Appointments]
        L2 --> L3[Contract · SignRequest]
        L3 --> L4[Payment · GoCardless]
    end

    RES -->|benchmarked Targets| CAMP
    CAMP -->|Targets routed into 0..1 Campaign| OUT
    OUT -->|non-responders after 3 mails| CON
    CON -->|appointment booked / interested| CLO

    RES -. "one Benchmark score, computed once" .-> CAMP
    CAMP -. benchmark .-> OUT
    OUT -. benchmark .-> CON
    CON -. benchmark .-> CLO

Stage by stage — what data and state moves:

1. Research — A ResearchJob (postal codes + industry + quantity, triggered manually or by cron) discovers companies via Serper.dev Maps and enriches each from several sources (Firecrawl crawl, Meta Ad Library, Wayback age, jobsuche.api.bund.dev). Every fact lands in research_data_points with provenance (source, retrieved_at, confidence). On completion the Benchmark engine computes a versioned 0–100 score across 5 weighted dimensions and denormalizes it onto the Target. Output: benchmarked, provenance-backed Targets.

2. Campaign assignment — Each researched Target is routed into 0..1 Campaign by that campaign's AssignmentRule — a threshold rule (numeric benchmark cutoff) or an LLM-prompt rule (natural-language match). Unmatched Targets stay "unassigned" and are re-checked later; re-assignment is supported. A Target older than 60 days is re-researched on assignment. Output: Targets attached to a Campaign, ready for its variants.

3. Outreach — A 3-mail sequence is sent from VirtualCompany / VirtualEmployee synthetic senders (Exchange Online via Microsoft Graph, warmed by Trulyinbox). At send time the Bandit (Thompson Sampling) selects the best-performing StepVersion; reply outcomes feed back as bandit_events (success = genuine reply). Sending order follows the benchmark. Output: replies advance toward Closing; non-responders after the 3rd mail hand off to Connect.

4. Connect — Supervisors define ConnectVariants (weekday/time windows) and schedule Shifts. On shift activation the system locks the top-N unworked Targets by benchmark into up to 4 Packages. Agents work a live call cockpit (CloudTalk power dialer, realtime via Socket.IO), recording disposition against the 8-stage connect pipeline. Output: an Appointment scheduled (or interested Target) hands off to Closing; KPIs and per-agent provisions accrue.

5. Closing — Interested Targets are round-robin assigned to a Closing-Agent (targets.closing_agent_id) and worked through a drag-drop 8-stage Kanban pipeline: appointments → contract send (SignRequest) → payment collection (GoCardless), with no-show tracking and warm handoffs. Output: Sold / Not sold / Unqualified end states.

Every transition across all stages is written to pipeline_events and mirrored into immutable audit_logs — the spine that Controlling reads for cross-stage KPIs. See 00-overview and 03-data-model for the full state machine.

2. Information architecture / navigation map

Primary navigation is grouped into four areas. The Pipeline group is ordered to mirror the funnel, so the nav itself teaches the mental model.

Hrunit CRM
├── Workspace
│   └── Dashboard        /dashboard    cross-funnel overview
├── Pipeline  (funnel order)
│   ├── Research         /research     discovery jobs + provenance
│   ├── Targets          /targets      benchmarked prospect companies
│   ├── Campaigns        /campaigns    campaign config + routing
│   ├── Outreach         /outreach     email sequences + bandit
│   ├── Connect          /connect      call cockpit + shifts
│   └── Closing          /closing      deal pipeline + contracts
├── Intelligence
│   └── Controlling      /controlling  cross-team analytics
└── Admin
    ├── Virtual Senders  /senders      sender identities + warmup
    ├── Settings         /settings     integrations, users, appearance
    └── Docs             /docs         design showcase + product docs

Workspace

Pipeline (in funnel order)

Intelligence

Admin

3. Roles → what they see

Four roles enforced by a per-resource permission layer (CASL). Least-privilege: agents see only their slice of the funnel.

✅ full access · ▫ read / limited · ▪ scoped subset · — hidden

• Admin — everything, including integration credentials, Virtual Senders, and budgets.
• Supervisor — the product owner's cockpit: campaigns, assignment rules, connect agents, shift scheduling, campaign releases, and Controlling.
• Connect-Agent — sees only released campaigns and works the call cockpit + assigned shifts; nothing is visible without a release.
• Closing-Agent — sees only their round-robin-assigned Targets and works the closing pipeline through to contract + payment.

4. Cross-cutting UX

• Benchmark is the universal sort key. The 0–100 score computed once in Research orders the Targets list, outreach send order, call-package composition, and shift assignment. Wherever Targets appear, they default to benchmark-descending. A benchmark breakdown ("why it scored") is always one click away.
• Provenance on demand. Every research fact carries source, retrieved_at, and confidence. The UI keeps profiles clean but surfaces a provenance drawer on any fact, so a user can always ask "where did this come from?" Manual edits are themselves provenance-tagged (manual:user_id:<id>).
• Live cockpit realtime. The Connect cockpit updates in real time over Socket.IO — CloudTalk call events reach the UI in under 500ms. Channels are per-user (user.{id}), per-shift (shift.{id}), and per-campaign (campaign.{id}.pipeline), so pipeline moves broadcast to every watcher without a refresh.
• Language: German default, English available. English in code, German in the UI; language is per-user (de / en).
• Light + dark. Theme-aware throughout via Tailwind 4 design tokens and shadcn/ui.
• Audit trail visibility. Every transition and change is append-only in pipeline_events / audit_logs and never edited or deleted. Admins get an audit-log viewer in Settings; the same events feed KPI dashboards and each Target's lifecycle timeline.

5. Screen inventory

See also: 00-overview · 01-architecture · 02-roadmap · 03-data-model · 04-design-workflow · product-requirements