Production-grade lead intelligence platform for B2B sales teams.
Irtiqa Intelligence automates lead discovery, enrichment, and prioritization through intelligent web scraping, technographic analysis, intent signal detection, and personalized outreach generation. Built with FastAPI, SQLAlchemy, and a modular agent-based architecture.
Irtiqa transforms raw company data into actionable sales intelligence through a multi-agent pipeline:
- Discover companies matching your ideal customer profile (ICP)
- Scrape and analyze company websites for technology signals
- Detect buying intent from hiring, funding, and technology changes
- Score leads using multi-factor intelligence scoring
- Personalize outreach messages based on company intelligence
Result: Prioritized, scored leads with context-aware outreach recommendations.
graph TD
subgraph Client["Client Layer"]
UI[Web UI / API Client]
end
subgraph API["API Layer (FastAPI)"]
Routes[REST Endpoints<br/>70+ endpoints]
Auth[JWT Authentication<br/>Multi-Tenancy]
end
subgraph Service["Service Layer"]
Services[Business Logic<br/>Transaction Boundaries]
end
subgraph Intelligence["Intelligence Layer"]
Workflows[3 Workflows<br/>Orchestration]
Agents[6 Agents<br/>Specialized Intelligence]
end
subgraph Data["Data Layer"]
Repos[Repositories<br/>Tenant Filtering]
ORM[SQLAlchemy ORM<br/>19 Tables]
end
subgraph Storage["Storage Layer"]
SQLite[(SQLite Dev)]
Postgres[(PostgreSQL Prod)]
end
subgraph Jobs["Background Jobs"]
Scheduler[Job Scheduler]
Runner[Job Runner]
end
UI -->|HTTP + JWT| Routes
Routes -->|Verify & Inject| Auth
Auth -->|Call Methods| Services
Services -->|Orchestrate| Workflows
Services -->|Execute| Agents
Workflows -->|Chain| Agents
Agents -->|Query/Persist| Repos
Services -->|Query/Persist| Repos
Repos -->|Map Entities| ORM
ORM -->|Connect| SQLite
ORM -->|Connect| Postgres
Services -.->|Schedule Async| Scheduler
Scheduler -->|Poll & Execute| Runner
Runner -->|Invoke| Workflows
Runner -->|Invoke| Agents
style API fill:#e1f5ff
style Service fill:#fff4e1
style Intelligence fill:#ffe1e1
style Data fill:#f0e1ff
style Storage fill:#e1ffe1
style Jobs fill:#ffe1f5
- RS256 JWT Authentication with JWKS endpoint for secure API access
- Email Verification and password reset workflows
- Organization Management with role-based access control (Owner, Admin, Member, Viewer)
- Tenant Isolation across all data and API endpoints
- Rate Limiting with database-backed tracking
flowchart LR
ICP[ICP Search<br/>Industry + Size + Tech] --> Discovery[Discovery Agent]
Discovery -->|Query| EDGAR[SEC EDGAR<br/>US Companies]
Discovery -->|Query| News[Google News RSS<br/>Funding Signals]
Discovery -->|Query| OC[OpenCorporates<br/>Global Registry]
EDGAR --> Dedupe[Deduplication<br/>Domain Matching]
News --> Dedupe
OC --> Dedupe
Dedupe --> Score[Discovery Score<br/>0.0-1.0]
Score --> Companies[(Companies<br/>needs_review)]
Companies -.->|Manual Trigger| Pipeline[Intelligence Pipeline]
style Discovery fill:#e1f5ff
style Dedupe fill:#fff4e1
style Score fill:#ffe1e1
style Companies fill:#e1ffe1
- ICP Search Management: Define and save ideal customer profile criteria
- Multi-Source Discovery: Automated searches across SEC EDGAR, Google News RSS, and OpenCorporates
- Smart Deduplication: Domain-based duplicate detection with fuzzy matching
- Discovery Scoring: Lightweight match quality scores (0.0-1.0) for prioritization
- Evidence Provenance: Full audit trail of discovery sources
flowchart LR
Input[Company Domain] --> DS[Deep Scraper<br/>Web Extraction]
DS -->|HTML + Text| Tech[Technographic<br/>Tech Detection]
Tech -->|40+ Signatures| Intent[Intent Signal<br/>Buying Signals]
Intent -->|8 Signal Types| Score[Intelligence Scoring<br/>Multi-Factor]
Score -->|Weighted Score| Person[Personalization<br/>Outreach Generation]
Person --> Output[Scored Lead<br/>+ Messages]
style DS fill:#e1f5ff
style Tech fill:#fff4e1
style Intent fill:#ffe1e1
style Score fill:#f0e1ff
style Person fill:#e1ffe1
6 Production Agents:
- Deep Scraper Agent: Web content extraction and parsing
- Technographic Agent: Technology detection (40+ signatures across 8 categories)
- Intent Signal Agent: Buying signal detection (8 signal families with deterministic rules)
- Intelligence Scoring Agent: Multi-factor lead scoring (fit, intent, technographic, engagement)
- Personalization Agent: Multi-variant outreach message generation
- Discovery Agent: ICP-based company discovery from external sources
📖 Agent System | 📖 Workflow System
- Aggregated Intelligence: Single endpoint returns companies with technologies, intent signals, scores, and outreach messages
- Smart Filtering: Filter by minimum score, pagination support
- Tenant-Scoped: Automatic organization isolation
- N+1 Prevention: Batch loading strategy for optimal performance
- Async Execution: Agent and workflow scheduling with status tracking
- Retry Policies: Exponential backoff with configurable limits
- Job Management: Schedule, cancel, retry, and monitor background tasks
- Provenance Tracking: Full audit trail for all intelligence data
- Source Linking: Evidence tied to agent runs, URLs, and API responses
- Confidence Scoring: Evidence quality metrics
- Score Refresh: Deterministic intelligence score recomputation
- Intelligence Pipeline: End-to-end enrichment (scrape → analyze → score → personalize)
- Discovery Pipeline: Company discovery orchestration (search → discover → deduplicate → create)
erDiagram
organizations ||--o{ companies : owns
organizations ||--o{ contacts : owns
companies ||--o{ websites : has
companies ||--o{ technologies : uses
companies ||--o{ intent_signals : emits
companies ||--o{ intelligence_scores : receives
companies ||--o{ outreach_messages : targeted_by
agent_runs ||--o{ technologies : detects
agent_runs ||--o{ intent_signals : finds
agent_runs ||--o{ intelligence_scores : computes
agent_runs ||--o{ outreach_messages : generates
agent_runs ||--o{ evidence_records : produces
discovery_searches ||--o{ discovery_runs : executes
discovery_searches ||--o{ companies : discovers
jobs ||--o{ agent_runs : triggers
19 Tables:
- 8 core intelligence tables (companies, contacts, websites, technologies, intent_signals, intelligence_scores, outreach_messages, evidence_records)
- 2 system tables (agent_runs, jobs)
- 2 discovery tables (discovery_searches, discovery_runs)
- 3 auth tables (users, organizations, memberships)
- 4 token tables (refresh_tokens, email_verification_tokens, password_reset_tokens, failed_login_attempts)
📖 Database Design | 📖 Entity Relationships
irtiqa-intelligence/
├── app/
│ ├── agents/ # 6 production agents
│ │ ├── deep_scraper/ # Web scraping & content extraction
│ │ ├── technographic/ # Technology detection (40+ signatures)
│ │ ├── intent_signal/ # Buying signal detection (8 families)
│ │ ├── intelligence_scoring/ # Lead scoring
│ │ ├── personalization/ # Outreach generation
│ │ └── discovery/ # Company discovery (3 sources)
│ ├── api/ # REST API endpoints (70+)
│ ├── core/ # Configuration, logging, errors
│ ├── database/ # Engine, session management
│ ├── jobs/ # Background job system
│ ├── models/ # SQLAlchemy ORM models (19 tables)
│ ├── repositories/ # Data access layer (15 repositories)
│ ├── schemas/ # Pydantic request/response schemas
│ ├── services/ # Business logic layer (15 services)
│ └── workflows/ # Multi-agent orchestration (3 workflows)
├── database/
│ └── migrations/ # Alembic migration scripts (8 revisions)
├── docs/ # Architecture & design documentation
├── tests/
│ ├── integration/ # End-to-end tests
│ └── unit/ # Component tests
└── README.md
| Layer | Technology | Purpose |
|---|---|---|
| Framework | FastAPI 0.115+ | Async web framework with OpenAPI |
| ORM | SQLAlchemy 2.0 | Database abstraction & query building |
| Migrations | Alembic 1.18+ | Schema versioning & evolution |
| Validation | Pydantic v2 | Request/response schemas |
| Database (Dev) | SQLite 3.x | Local development with WAL mode |
| Database (Prod) | PostgreSQL 18+ | Production-grade relational database |
| HTTP Client | httpx | Async HTTP for external API calls |
| Parsing | BeautifulSoup4, feedparser | HTML & RSS feed parsing |
| Testing | pytest, pytest-asyncio | Test framework with async support |
| CI/CD | GitHub Actions | Automated testing & validation |
flowchart LR
Push[Git Push/PR] --> CI[GitHub Actions]
CI --> Validate[Validation]
CI --> Test[Testing]
Validate --> Ruff[Ruff Lint<br/>Advisory]
Validate --> Mypy[Mypy Types<br/>Advisory]
Validate --> Compile[compileall<br/>BLOCKING]
Test --> Migrate[Alembic Upgrade<br/>BLOCKING]
Test --> Drift[Schema Drift Check<br/>BLOCKING]
Test --> SQLiteTests[SQLite Tests<br/>606 tests<br/>BLOCKING]
Test --> PGTests[PostgreSQL Tests<br/>27 tests<br/>BLOCKING]
Compile --> Result{All Pass?}
Migrate --> Result
Drift --> Result
SQLiteTests --> Result
PGTests --> Result
Result -->|Yes| Success[✓ CI Pass]
Result -->|No| Failure[✗ CI Fail]
style Success fill:#e1ffe1
style Failure fill:#ffe1e1
633 Tests (606 SQLite, 27 PostgreSQL compatibility)
100% Pass Rate on main branch
Test Coverage:
- Unit tests for agents, services, schemas, workflows
- Integration tests for API endpoints, repositories, pipelines
- Database tests for migrations, constraints, transactions
- PostgreSQL compatibility verification
# Clone repository
git clone https://github.com/Luffyz/irtiqa-intelligence.git
cd irtiqa-intelligence
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # Linux/Mac
.venv\Scripts\activate # Windows
# Install dependencies
pip install -e .[dev]
# For PostgreSQL support
pip install "psycopg[binary]>=3.2.0"
# Configure environment
cp .env.example .env
# Edit .env with your settings# Apply database schema
python -m alembic upgrade head
# Check for schema drift
python -m alembic check# Start FastAPI server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000API Documentation:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
# Execute full test suite
python -m pytest
# Run with coverage
python -m pytest --cov=app --cov-report=html
# Run specific test categories
python -m pytest tests/unit/
python -m pytest tests/integration/- README — This file (overview, setup, quick start)
- Architecture Overview — System layers, request lifecycle, patterns
- Database Design — Schema, tables, constraints, migrations
- Entity Relationships — FK relationships, cascade rules
- Agent System — All 6 agents, responsibilities, lifecycles
- Workflow System — Workflow orchestration, implementations
- Background Jobs — Async execution, retry policies
- Discovery Engine — ICP search, external sources, deduplication
- Authentication — JWT, multi-tenancy, RBAC
- Evidence System — Provenance tracking
- Agent Interface Design — BaseAgent pattern details
- Deep Scraper Design — Web scraping architecture
- Technographic Agent Design — Technology detection
- Intent Signal Agent Design — Buying signal rules
- Personalization Agent Design — Outreach generation
The backend is production-ready with all planned features implemented:
- ✅ Authentication & multi-tenancy
- ✅ Lead discovery engine
- ✅ Intelligence pipeline (6 agents)
- ✅ Workflow orchestration
- ✅ Background job system
- ✅ REST API (70+ endpoints)
- ✅ 633 automated tests
Phase 1: Frontend Development
- React/Vue.js web application
- ICP search builder UI
- Discovery run monitoring dashboard
- Lead review & enrichment interface
- Intelligence score visualization
Phase 2: Production Deployment
- Docker containerization
- PostgreSQL database migration
- Kubernetes/cloud deployment manifests
- CI/CD pipeline for releases
- Monitoring & observability (Grafana, Prometheus)
Phase 3: Advanced Features
- Scheduled discovery runs (daily/weekly ICP searches)
- ML-based lead scoring models
- CRM integrations (Salesforce, HubSpot)
- Email automation & outreach tracking
- Advanced analytics & reporting
Contributions are welcome! Please follow these guidelines:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes with tests
- Ensure all tests pass (
python -m pytest) - Check for schema drift (
python -m alembic check) - Commit with descriptive messages
- Push to your fork and submit a pull request
This project is proprietary software. All rights reserved.
Built with:
- FastAPI — Modern Python web framework
- SQLAlchemy — Python SQL toolkit
- Alembic — Database migrations
- Pydantic — Data validation
- pytest — Testing framework
Production-Ready Backend · 633 Tests · 19 Database Tables · 6 Intelligence Agents · 70+ API Endpoints