Your Role as Administrator

As an Administrator in BidFactory, you have full system access and are responsible for the health, configuration, and governance of the entire platform. You are the single point of authority for user accounts, monitoring configuration, ingestion operations, and system troubleshooting. This manual covers every administrative capability in detail.

Key Responsibilities

Administrators are responsible for the platform across all operational domains:

• User Management — Create, edit, deactivate, and assign roles to all user accounts. Manage password resets and access control.
• System Configuration — Configure monitoring criteria (CPV codes, keywords, value ranges, geographic scope), portal connections (TED, BKMS, Cosinex VMP), and notification settings.
• Ingestion Operations — Trigger and monitor data ingestion runs from TED and BKMS. Review ingestion history, diagnose failures, and manage rate limits.
• System Health Monitoring — Monitor service status for all 5 Docker Compose services. Review logs, diagnose errors, and execute recovery procedures.
• Data Governance — Oversee competitor merges, manage the knowledge base, and ensure data integrity across all entities.
• Security — Enforce JWT token policy, manage CORS configuration, apply rate limiting, and respond to authentication anomalies.
• Bid Lifecycle Oversight — Full read and write access to all bids, tasks, proposals, and competitor records. Can perform any action available to Bid Managers, SMEs, and Approvers.

What You Can Do

The Administrator role has unrestricted access to all platform capabilities:

• All actions available to Bid Managers, SMEs, and Approvers
• Create, edit, deactivate, and delete user accounts
• Assign and change user roles
• Configure monitoring criteria and portal connections
• Trigger ingestion runs and view full ingestion history
• View and manage all bids, tasks, documents, and proposals
• Merge and delete competitors
• Trigger AI enrichment for any competitor
• Approve gate decisions (AR2, AR3)
• Update the Company Profile
• Access Docker Compose diagnostic commands and service logs
• Manage database migrations and system configuration

Admin-Exclusive Capabilities

The following capabilities are restricted to the Administrator role and are not available to Bid Managers, SMEs, or Approvers:

• User Management — The /admin/users page and all user CRUD operations
• Monitoring Settings — Configuring CPV codes, keywords, value ranges, portal toggles, and ingestion schedules
• AI Provider Settings — Configuring LLM API keys, model routing per role, feature toggles, and monitoring token usage and costs
• Ingestion Triggers — The “Run Now” button and /api/v1/ingest/trigger endpoint
• Ingestion Run History — Full view of all ingestion runs including error messages and partial failure details
• System Diagnostics — Access to Docker service health, container logs, and database status endpoints
• Competitor Deletion and Merging — Permanent data operations that cannot be undone

Installation & Setup

BidFactory runs as a Docker Compose stack of five services. This chapter covers the full installation process from cloning the repository to verifying a running stack.

Installation Steps

1 BidFactory landing page confirming a successful deployment — all services healthy

Step 1 — Prerequisites

Ensure the following are installed on the host machine before proceeding:

• Docker 24.0 or later
• Docker Compose v2.20 or later (included with Docker Desktop)
• Git 2.40 or later
• Minimum 4 GB RAM and 10 GB free disk space for the full stack

Step 2 — Clone the Repository

git clone https://github.com/your-org/bidfactory.git
cd bidfactory

Step 3 — Configure Environment Variables

Copy the example environment file and fill in your values:

cp .env.example .env

Open .env in a text editor. The following variables are required before first launch:

• SECRET_KEY — A strong random string (at least 64 characters). Used for JWT signing.
• DATABASE_URL — PostgreSQL connection string (default: postgresql://bidfactory:bidfactory@db:5432/bidfactory)
• REDIS_URL — Redis connection string (default: redis://redis:6379/0)
• ANTHROPIC_API_KEY — Your Anthropic API key for AI enrichment and proposal generation features
• CORS_ORIGINS — Comma-separated list of allowed origins (e.g., http://localhost:3000)
• ADMIN_EMAIL — Email address for the initial admin user created on first run
• ADMIN_PASSWORD — Initial admin password (change immediately after first login)

Step 4 — Build and Start the Stack

From the bidfactory/ directory, run:

docker compose up --build

The first build will pull base images and compile all services. Subsequent starts use cached layers and are significantly faster. To run the stack in the background (detached mode):

docker compose up --build -d

Step 5 — Database Migrations

On first launch, the backend automatically runs Alembic migrations to create the database schema. If you need to run migrations manually:

docker compose exec backend alembic upgrade head

Verify the Stack

After startup, verify all services are running correctly:

docker compose ps

All five services should show a status of Up or running (healthy).

Service Overview

Health Check Endpoints

The backend exposes health check endpoints you can poll directly:

# Overall API health
curl http://localhost:8000/health

# Database connectivity
curl http://localhost:8000/health/db

# Redis connectivity
curl http://localhost:8000/health/redis

A healthy response returns {"status": "ok"} for each endpoint.

Access the Platform

• Frontend UI: http://localhost:3000
• Backend API docs (Swagger): http://localhost:8000/docs
• Backend API docs (ReDoc): http://localhost:8000/redoc

Environment Reference

The complete list of supported environment variables is maintained in .env.example at the project root. Key optional settings include:

First Login & Interface

Logging In

2 The BidFactory login page — enter your administrator credentials

Navigate to http://localhost:3000/login (or your deployment URL). Use the credentials set in your .env file via ADMIN_EMAIL and ADMIN_PASSWORD.

Authentication Flow

BidFactory uses stateless JWT-based authentication:

• On successful login, the server issues an access token (valid for 24 hours by default, configurable via ACCESS_TOKEN_EXPIRE_MINUTES) and a refresh token (valid for 7 days).
• The frontend stores tokens in HTTP-only cookies — they are not accessible via JavaScript, mitigating XSS risks.
• The refresh token is used automatically to obtain a new access token as it approaches expiry, so active sessions continue seamlessly.
• After 7 days of inactivity (or explicit logout), both tokens expire and the user must log in again.

Interface Layout

3 The BidFactory interface — sidebar navigation, header controls, and main content area

The BidFactory interface consists of four primary areas:

• Left Sidebar — Dark navy navigation panel with links to all sections. As an Administrator, you will see additional items not visible to other roles: Settings (monitoring criteria, portals, and AI provider configuration) and Admin (user management). The sidebar includes a reading progress bar at the bottom.
• Top Header Bar — Contains the global search field (activate with Ctrl+K or Cmd+K), a notification bell with unread count badge, and your user avatar. The avatar dropdown provides quick access to your profile, settings, and the sign-out action.
• Main Content Area — The central workspace displaying the currently selected page. Context-sensitive action buttons and filters appear within this area.
• Deadline Sidebar — On the Dashboard page, a right-hand panel shows upcoming deadlines for the next 14 days with color-coded urgency indicators.

User Management

User management is an administrator-exclusive capability. Navigate to Admin → Users (or directly to /admin/users) to access the user management console. From here you can create accounts, edit profiles, assign roles, and deactivate users who should no longer have access.

Creating a New User

Click the “New User” button to open the user creation form. Complete all required fields:

• Email — Must be a valid, unique email address. Used for notifications and password resets.
• Username — Unique identifier used for login. Alphanumeric characters and underscores only, 3–32 characters.
• Full Name — Display name shown in the interface, task assignments, and bid cards.
• Password — Must meet minimum requirements: at least 8 characters, at least one uppercase letter, one lowercase letter, and one digit. The user should be told to change this on first login.
• Role — Assign one of the four available roles (see the Role Reference table below).
• Active — Toggle to activate or deactivate the account. Inactive accounts cannot log in.

Role Reference

BidFactory has four roles, each providing a distinct set of permissions aligned with a specific job function:

Permission Matrix

The following table shows which actions are permitted per role across all major platform features:

Editing Users

Click the edit icon next to any user in the user list to open their profile for editing. You can change any field including their role. Changes take effect immediately — active sessions using the old role will reflect the new role on their next request.

Deactivating Accounts

Toggle the Active switch to deactivate an account. Deactivated users cannot log in and their existing sessions are invalidated within minutes. Deactivation is reversible — you can reactivate an account at any time. To permanently remove a user, use the Delete action (requires confirmation).

Monitoring Settings

Monitoring Settings is an administrator-exclusive section that controls how BidFactory discovers new tenders. Navigate to Settings → Monitoring to access the three configuration tabs: Criteria, Portals, and Run History.

4 Monitoring Settings — configure what to monitor and from which portals

Criteria Tab

Criteria define the filter conditions applied when scanning tender portals. Each ingestion run uses these criteria to determine which tenders are relevant and should appear in the Discovery queue. Criteria use OR logic — a tender matches if it satisfies any one criterion.

Portals Tab

The Portals tab controls which procurement data sources are queried during ingestion. Each portal has an individual enable/disable toggle and displays the last successful sync timestamp.

Run History Tab

The Run History tab shows a log of all completed and in-progress ingestion runs. Each row represents a single run and displays:

Run Now Button

Click “Run Now” to trigger an immediate ingestion run across all enabled portals. This button is rate-limited: only one manual trigger is allowed per 5-minute window to prevent accidental API hammering. If the button is greyed out, wait for the cooldown to expire.

Dashboard

The Dashboard is the home screen after login and provides a real-time overview of the entire bid pipeline. It refreshes automatically every 60 seconds to show current status without manual page reloads.

5 Dashboard in Kanban view — four metric cards, phase pipeline tracker, and bid cards by phase

Metric Cards and Pipeline Tracker

At the top of the Dashboard, four metric cards summarize the current pipeline state:

Below the cards, a 9-node visual pipeline shows the count of bids in each phase. Nodes are connected by flow lines showing the progression path from Qualification to Submitted/Won/Lost.

Kanban Board

The default Kanban view displays bid cards organized in columns, one per pipeline phase. Each card shows:

• Bid title and reference number
• Estimated contract value
• Submission deadline with color-coded urgency chip
• Priority indicator (Critical, High, Medium, Low)
• Assigned manager avatar
• Advance Phase button (hover to reveal) — available to Admin and Bid Manager roles

Click any card to navigate to the full bid detail page. Hover over a card to see the Advance Phase button, which moves the bid to the next pipeline phase with a confirmation dialog.

Table View

6 Dashboard in Table view — sortable columns for bulk scanning of all bids

Toggle to Table view using the view-switcher buttons above the Kanban board. The table shows all bids in a compact sortable list with columns for: Title, Phase, Status, Priority, Value, Deadline, and Manager. Click any column header to sort ascending/descending. Click a bid title to open the detail page.

Deadline Sidebar

The right side of the Dashboard shows a Next 14 Days deadline panel listing all bid submission deadlines and task deadlines within the next two weeks. Each item is color-coded:

• Overdue — Past the deadline, requires immediate attention
• 0–3 days — Urgent, needs action today or tomorrow
• 4–7 days — Approaching, plan your work now
• 8–14 days — On track, monitor regularly

As administrator, you see deadlines across all bids and all users, giving you full pipeline visibility for resource management and escalation decisions.

Tender Discovery

The Discovery section is where newly ingested tenders arrive for review and triage. As an administrator, you have full access to all Discovery actions including intake, dismissal, and import.

7 Tender Discovery queue — filter and triage incoming tenders from configured portals

Discovery Queue

The Discovery queue lists all tenders that have been ingested and match your monitoring criteria but have not yet been intaken into the bid pipeline or dismissed. New tenders appear here within minutes of ingestion completing.

Filters

Six filter controls narrow the queue to the tenders most relevant to your current review:

Queue Table Columns

The queue table shows: Title, Contracting Authority, Country, CPV Code, Estimated Value, Publication Date, Deadline, Source Portal, and action buttons. All columns are sortable. Pagination defaults to 20 items per page (max 100).

Intake and Dismiss Workflows

Manual Import

Navigate to Discovery → Import to manually add a tender that was not captured by automated ingestion. Provide the tender URL or paste the tender reference number to fetch it directly from the source portal API. Manual import is subject to the same rate limits as scheduled ingestion — the backend enforces a minimum interval between requests to a given portal to avoid being throttled.

Bid Management

The Bids section is the core of BidFactory. As an administrator, you have full read and write access to all bids: you can create, edit, advance phases, assign tasks, manage documents, generate proposals, and track progress across the entire pipeline.

Bids List

8 Bids list — filter, sort, and access all bids in the pipeline

Navigate to Bids in the sidebar to view all bids in the system. Filter controls at the top of the list allow you to narrow results by:

• Search — Bid title or keywords in the description
• Phase — Any of the 9 pipeline phases
• Status — Active, No Bid, Won, Lost, Withdrawn, On Hold, or Submitted
• Priority — Critical, High, Medium, or Low
• Assigned Manager — Filter to bids assigned to a specific user
• Date Range — Filter by intake date or submission deadline

Creating a New Bid

Click “New Bid” to create a bid manually (without going through the Discovery intake flow). Provide: title, contracting authority, estimated value, submission deadline, CPV code, source portal (or “Direct” for bids sourced outside the configured portals), assigned manager, and priority. The bid is created in the Qualification phase.

Bid Detail Page

9 Bid detail page — status bar, 9-phase stepper, and tabbed content areas

Click any bid title to open its detail page. The page is structured as:

• Status Bar — Displays the bid title, current phase badge, status badge, priority badge, and key dates (intake date, submission deadline). Admin and Bid Manager users see an “Advance Phase” button here.
• 9-Phase Stepper — A horizontal progress tracker showing all phases. Completed phases are highlighted; the current phase is active; future phases are greyed. Click any completed phase to view its notes.
• Tab Navigation — Below the stepper, tabs provide access to Overview, Tasks, Documents, Proposals, Competitors, and the Bid Resources card.

Bid Resources Card

The Bid Resources card (visible in the Overview tab) provides quick links to all documents, Knowledge Base assets, and external resources associated with the bid. It serves as a single navigation hub for all bid-related materials without switching between sections.

Pipeline Phases and Statuses

BidFactory uses a 9-phase pipeline designed around best-practice bid lifecycle management:

Bid Statuses

Bid Priorities

Document Processing

BidFactory can ingest, parse, and extract structured information from tender documents attached to a bid. Document processing happens in the context of a specific bid, accessible from the Documents tab on the bid detail page.

Uploading Documents

Click “Upload Document” within the Documents tab to attach files to a bid. Supported formats:

Drag and drop files onto the upload zone or click to browse. Multiple files can be uploaded simultaneously. Maximum file size is 50 MB per file.

AI Extraction Workflow

After upload, click “Extract” on a document to trigger structured data extraction. The extraction engine processes the document and populates nine structured sections:

• Scope of Work — Core deliverables and service requirements
• Eligibility Criteria — Mandatory qualifications and exclusion grounds
• Evaluation Criteria — Award criteria and weightings
• Contract Duration — Start date, end date, extension options
• Estimated Value — Budget range or ceiling value
• Submission Requirements — Required documents and formatting rules
• Key Dates — Clarification deadline, submission deadline, award date
• Contact Information — Contracting officer name, email, telephone
• Special Conditions — Security clearance, insurance, performance bond requirements

AI Indicators and Approval Workflow

Fields where the extraction confidence is below 90% are flagged with an [AI] indicator badge. These fields require human review before the bid can advance past the RFP Analysis phase. The approval workflow is:

1. Review each flagged field in context of the source document
2. Edit the value if the extraction is incorrect or incomplete
3. Click the checkmark next to each field to approve it
4. Once all [AI]-flagged fields are approved, the extraction status updates to Verified

RFI Auto-Fill

When processing documents for bids in the RFI phase, the extraction engine also generates pre-filled answers to common RFI questions using data from the Knowledge Base. Each auto-filled field displays a confidence indicator:

Each auto-filled field shows the source Knowledge Base asset it was drawn from, so you can verify accuracy and update the source asset if needed for future RFIs.

Proposal Generation

BidFactory’s AI-assisted proposal generation creates structured first drafts using Claude API and your Knowledge Base content. Proposals are accessible from the Proposals tab on the bid detail page.

Quick Generate

Quick Generate creates a complete proposal draft with a single click using default section templates and available Knowledge Base content. It is designed for rapid first drafts where the goal is to produce reviewable content quickly rather than maximally customized output. The generation runs as a background ARQ job — a shimmer progress bar in the header indicates the job is in progress. Generation typically completes in 60–120 seconds depending on proposal length and Claude API latency.

Guided Generate (GEM Wizard)

Guided Generate launches the GEM (Guided Excellence Methodology) wizard, a step-by-step process for configuring each section of the proposal before generation begins. The wizard has the following steps:

1. Section Selection — Choose which of the 8 section types to include in this proposal
2. Win Themes — Enter 3–5 win themes that should be woven throughout the proposal
3. Knowledge Base Assets — Review and select which capabilities, case studies, and references to draw from
4. Competitor Context — Optionally include competitor intelligence to inform differentiating language
5. Tone and Length — Set formality level (formal/semi-formal) and target word count per section
6. Review and Generate — Final confirmation before submitting the generation job

Section Types

BidFactory supports 8 configurable proposal section types:

• Executive Summary — High-level overview for senior evaluators
• Technical Approach — Methodology, tools, and technical solution description
• Management Approach — Team structure, governance, and delivery management
• Past Performance — Relevant case studies and references
• Team Qualifications — Key personnel CVs and credentials
• Risk Management — Identified risks and mitigation strategies
• Innovation — Novel approaches, tools, or differentiators
• Compliance Matrix — Requirement-by-requirement compliance table

Multi-Language Support

Proposals can be generated in English, German, or French. Language selection is available in both Quick Generate and the GEM wizard. The generation workflow is:

1. Content is always generated first in English regardless of target language
2. If a non-English language is selected, the English draft is then translated via a second Claude API call
3. Both the English source and the translated version are stored and can be reviewed independently

This “generate-then-translate” approach preserves quality by generating in the language the AI model performs best in, then applying a targeted translation rather than generating directly in a second language.

Template System and PDF Export

BidFactory includes 16 proposal templates covering common procurement categories. Templates define section order, formatting rules, and default win themes for their category. Templates are accessible from the Templates section in the sidebar.

PDF Export

To export a completed proposal as PDF, click “Export PDF” in the proposal actions menu. The export uses WeasyPrint to render the proposal with:

• Branded cover page with your company logo and bid metadata
• Automatically generated Table of Contents with page numbers
• Language filtering (if multi-language content exists, select which language to include)
• Page headers and footers with confidentiality notice and page numbers

PDF generation is a background task. When complete, a download link appears in the notification center and on the Proposals tab.

Competitor Intelligence

BidFactory maintains a database of competitor organizations built from award data extracted during tender ingestion. The Competitor Intelligence section provides tools for managing this database, enriching profiles with AI-generated intelligence, and analyzing competitive positioning.

10 Competitor Intelligence — searchable list of known competitors with award data

Competitor List

Navigate to Competitors in the sidebar to see all known competitor organizations. Filter the list by: company name, country, sector (CPV-based), or award date range. Each competitor card shows the company name, country of registration, number of awards in the database, and last enrichment date.

Adding a Competitor Manually

Click “Add Competitor” to manually register an organization that does not yet appear in the database (e.g., a known competitor that has not yet appeared in your monitored tenders). Provide: company name, country, and optional website URL. The entity resolution system will automatically detect and merge duplicates if the same company is later encountered during ingestion.

Merging Competitors (Admin Only)

Duplicate competitor records can occur when the same organization is referenced under slightly different names across tender databases. Administrators can merge two records into one. Navigate to the competitor profile, click “Merge”, and select the target record to merge into.

AI Enrichment

Enrichment uses web search and Claude API to generate a structured intelligence profile for a competitor. Click “Enrich” on any competitor profile to trigger the enrichment job. The job runs in the background via the ARQ worker and typically completes in 30–90 seconds.

Enrichment generates or updates the following profile sections:

• Company description and business summary
• Key service areas and capabilities
• Known clients (public sector focus)
• Estimated annual revenue range
• Recent awards and contract wins
• Strategic positioning and notable differentiators

CB Insights Export

Competitor data can be exported to CSV in CB Insights format for use with external analysis tools. From the Competitors list, select the competitors to export and click “Export → CB Insights CSV”.

SWOT Analysis per Bid

From within a bid’s Competitors tab, you can generate a SWOT analysis that evaluates a specific competitor in the context of this specific bid. The analysis covers:

• Strengths — Competitor advantages relevant to this tender’s evaluation criteria
• Weaknesses — Known gaps or disadvantages relative to the tender requirements
• Opportunities — Areas where your organization can differentiate effectively
• Threats — Risks posed by this competitor’s likely approach
• Win Probability — A calculated estimate (0–100%) based on award history, enrichment data, and bid characteristics

Market Benchmarking

The Benchmarking view (accessible from the Analytics section) provides aggregate competitive market intelligence across a configurable 2-year rolling window. Metrics include:

• Win rate by competitor and by CPV sector
• Average contract values by category
• Day-rate estimates derived from public award data and contract durations
• Market share by contracting authority type
• Competitive concentration index by sector

Knowledge Base

The Knowledge Base stores reusable content assets that power proposal generation, RFI auto-fill, and personnel assignments. It is a shared organizational resource, accessible to all roles for reading and to Admin, Bid Manager, and SME roles for editing.

11 Knowledge Base — organized library of reusable bid content assets

Asset Types

The Knowledge Base supports 12 distinct asset types, each with its own structured metadata schema:

Full-Text Search

The Knowledge Base uses PostgreSQL tsvector full-text search with GIN indexing for fast, relevance-ranked search across all asset titles, descriptions, and body text. Type any keywords in the search bar to find relevant assets instantly. Results are ranked by relevance score. Advanced filter controls allow narrowing by asset type, CPV sector, language, and upload date.

Personnel Profiles

Personnel profiles in the Knowledge Base represent the CVs and biographies of key personnel who may be named in proposals. Each profile includes:

• Full name, title, and summary biography
• Qualifications and certifications (linked to Certification assets)
• Years of experience by discipline
• Project history with roles and outcomes
• Languages and clearance levels
• Photo (optional, used in formatted PDF proposals)

Personnel profiles are updated by SMEs and Bid Managers. Keeping profiles current ensures that proposal generators can accurately represent team qualifications.

Company Profile

The Company Profile contains your organization’s master information used across all proposals and RFI responses. Fields include: company legal name, registration number, VAT number, registered address, primary contact, company description, key sectors, certifications list, and insurance summary.

Analytics

The Analytics section provides data-driven insights into your bid pipeline performance, win rates, competitive positioning, and resource utilization. All analytics are available to all roles.

12 Analytics — pipeline performance metrics and visual trend charts

Date Range Filtering and Summary Cards

Select a date range at the top of the Analytics page to filter all charts and metrics. The date range applies to bid intake date by default; toggle to filter by submission date or award date as needed. Four summary cards show aggregate statistics for the selected period:

Chart Library

The analytics page contains the following charts, all responsive and interactive (hover for tooltips, click legend items to toggle series):

• Win Rate Trend — Month-by-month win rate percentage over time. Useful for identifying seasonal patterns and the impact of process changes.
• Bids by Phase — Current snapshot of bid count per pipeline phase. Identifies bottlenecks where bids are accumulating.
• Pipeline Funnel — Conversion rates between each pipeline phase showing where bids drop out. Calculated for the selected date range.
• Volume by CPV Sector — Stacked bar chart showing bid volume and win volume by CPV code category. Identifies your strongest and weakest sectors.
• Phase Duration — Box plot showing average and distribution of time spent in each phase. Helps identify phases that consistently take longer than expected.
• No-Bid Reasons — Pie chart of dismissal and no-bid decision reasons. Highlights systematic issues (e.g., high “resource conflict” rate signals capacity constraints).
• Conversion Rates — Funnel visualization from Discovery queue through to Won contracts, showing the full lead-to-win conversion across the entire pipeline.

Notifications

BidFactory generates in-platform notifications for key bid lifecycle events and system events. Administrators receive all notification types, including system-level alerts not visible to other roles.

Notification Types

Notification Center

The notification bell in the top header displays an unread count badge. The badge updates every 30 seconds via polling. Click the bell to open the notification center, which shows:

• All unread notifications sorted by recency (newest first)
• A “Mark all as read” button
• Individual notification entries with: type icon, message, related bid link, and timestamp
• Older notifications are paginated in sets of 20

Click any notification to navigate directly to the relevant bid, task, or competitor. Clicking marks the notification as read.

Background Tasks for Deadlines

Deadline reminder notifications are generated by a background ARQ job that runs every hour. The job checks all active bids and sends notifications at:

• 48 hours before deadline — First reminder to the assigned bid manager and all admin users
• 24 hours before deadline — Urgent reminder with escalation flag
• Overdue (deadline passed) — Critical notification; the bid deadline indicator turns red in the dashboard

Email notifications for deadline reminders are queued in Redis and processed by the worker service. Configure the email server connection in your .env file via SMTP_HOST, SMTP_PORT, SMTP_USER, and SMTP_PASSWORD.

System Troubleshooting

This chapter covers administrator-exclusive diagnostic procedures. These commands and techniques require access to the Docker host and are not available through the web interface.

Common Issues

docker compose logs backend --tail=50 | grep "auth"

docker compose logs worker --tail=100 | grep -i "ingest"

docker compose ps
curl http://localhost:8000/health
curl http://localhost:8000/health/db
curl http://localhost:8000/health/redis

docker stats --no-stream

docker compose logs backend --tail=200 | grep "slow_query"

docker compose exec redis redis-cli LLEN arq:queue:default

curl http://localhost:8000/health/db
curl http://localhost:8000/health/redis

docker compose logs backend --tail=100 | grep -i "circuit"

docker compose restart backend

docker compose exec backend alembic current

docker compose exec backend alembic history --verbose

docker compose exec backend alembic upgrade head

docker compose ps worker
docker compose logs worker --tail=50

docker compose logs worker --tail=100 | grep -i "claude\|anthropic"

docker compose exec backend python -c "import os; print(bool(os.getenv('ANTHROPIC_API_KEY')))"

Diagnostic Command Reference

All commands must be run from the bidfactory/ directory on the Docker host:

# Check status of all 5 services
docker compose ps

# Tail logs for a specific service (replace 'backend' with service name)
docker compose logs backend --follow --tail=100

# Check database connectivity
docker compose exec backend python -c "from app.db.session import engine; engine.connect(); print('DB OK')"

# Ping Redis
docker compose exec redis redis-cli ping

# Full health check via API
curl http://localhost:8000/health

# View container resource usage
docker stats --no-stream

# Restart a single service without affecting others
docker compose restart backend

# Rebuild and restart a single service after code change
docker compose up --build -d backend

# Run database migrations
docker compose exec backend alembic upgrade head

# Check Alembic migration status
docker compose exec backend alembic current

# View ARQ job queue length
docker compose exec redis redis-cli LLEN arq:queue:default

# Force stop and clean restart of entire stack
docker compose down && docker compose up --build -d

AI Provider Settings

BidFactory uses large language models (LLMs) for document extraction, proposal generation, competitor enrichment, SWOT analysis, RFI autofill, and translation. The AI Provider Settings page lets you configure which providers, models, and features are used across the platform. Navigate to Admin → Settings in the sidebar to access this page.

The page is organised into four tabs: Keys, Routing, Toggles, and Usage.

Keys Tab — API Provider Configuration

The Keys tab displays two provider cards side by side: Anthropic (Claude models) and OpenAI (GPT models). Each card contains:

• API Key — A masked password field. Keys are encrypted at rest using Fernet symmetric encryption derived from the application’s SECRET_KEY. A source badge shows whether the current value comes from the DB (database) or ENV (environment variable fallback).
• Model — The default model for this provider (e.g., claude-sonnet-4-5-20250929 for Anthropic or gpt-4o for OpenAI). This is used as the fallback when no role-specific model is configured.
• Save — Changes are submitted per provider card. The button is disabled until a change is detected.

Routing Tab — Role-Based Model Assignment

BidFactory defines four LLM roles, each handling a different category of AI work. The Routing tab shows one card per role, allowing you to assign a specific provider and model to each:

Each role card provides:

• Provider dropdown — Choose between Anthropic and OpenAI. Changing the provider clears the model selection so you must re-select a model.
• Model dropdown — Lists available models for the selected provider. Anthropic options include claude-3-5-haiku-latest, claude-3-5-sonnet-latest, claude-3-opus-latest, and claude-sonnet-4-5-20250929. OpenAI options include gpt-4.1-mini, gpt-4o-mini, gpt-4.1, and gpt-4o. Select Custom… to enter any model name manually (useful for newly released models or fine-tuned variants).
• Save — Provider and model are saved together.

Toggles Tab — Feature Flags

The Toggles tab provides on/off switches for experimental and optimisation features. Each toggle saves immediately when clicked — no separate Save button is needed.

Usage Tab — LLM Analytics Dashboard

The Usage tab provides full observability into all LLM API calls made by the platform. Every call — whether for extraction, proposal generation, enrichment, or translation — is logged with token counts, cost, latency, and success/failure status.

Filters

At the top of the Usage tab you can filter the data by:

• Date range — From/To date pickers (defaults to the last 30 days)
• Provider — All, Anthropic, or OpenAI
• Role — All, Extractor, Writer, Enrichment, or Escalation

KPI Summary Cards

Five cards display aggregate metrics for the filtered period:

Usage Chart

A bar chart (powered by Recharts) visualises token usage and call counts grouped by model and role. This makes it easy to identify which operations consume the most resources.

Aggregation Table

Below the chart, an aggregation table breaks down usage by provider, model, and role combination. Columns include call count, total tokens, total cost (USD), and average latency. Use this to compare cost efficiency across providers.

Event Log

The bottom section shows a paginated table of individual LLM events (20 per page). Each row includes:

• Time — When the API call was made
• Provider and Model — Which LLM handled the request
• Role and Job Type — The purpose (e.g., writer / proposal_generation)
• Tokens — Input + output token count
• Cost — Computed cost in USD
• Latency — Response time in milliseconds
• Status — OK or ERR badge. Failed calls include the error message.

CSV Export

Click the Export CSV button to download all usage events for the selected date range as a CSV file. The file includes all columns from the event log and is named llm-usage-{from}_{to}.csv. Use this for external reporting, cost allocation, or audit purposes.

Shortcuts & Accessibility

Keyboard Shortcuts

BidFactory supports the following keyboard shortcuts to speed up navigation and common actions:

Responsive Design and Accessibility

Responsive Breakpoints

• Desktop (>1024px) — Full two-column layout: sidebar always visible, full-width content area
• Tablet (768px–1024px) — Compressed sidebar (260px), content area adjusts padding
• Mobile (<768px) — Sidebar hidden by default, accessible via hamburger button in top-left. Content fills the full viewport width.

WCAG 2.1 AA Compliance

BidFactory’s frontend is designed to meet WCAG 2.1 Level AA accessibility guidelines:

• Colour contrast — All text meets a minimum 4.5:1 contrast ratio against its background. UI controls meet 3:1 for non-text elements.
• Keyboard navigation — Every interactive element is reachable and operable via keyboard alone. Focus indicators are clearly visible.
• Screen reader support — Semantic HTML elements, ARIA labels on icon-only buttons, and live regions for dynamic content updates.
• Form labels — All form fields have associated visible labels. Error messages are programmatically associated with their fields.
• Image alt text — All informational images have descriptive alternative text. Decorative images have empty alt="" attributes.

Glossary

This glossary defines key terms used throughout the BidFactory platform and this manual, including both procurement terminology and technical platform concepts.

Role Permission Matrix

Complete reference of all platform features and the roles that can access each one. This matrix supersedes any partial tables elsewhere in this manual.