FairFlow

FairFlow is an analytics platform for exhibitions, fairs, and branded activations. It helps teams understand how people behave inside physical spaces by converting indoor movement data into clear, decision-ready insights.

Most offline activations still rely on attendance counts, manual observation, and post-event assumptions. That creates a gap for marketing agencies and organizers: they can report presence, but not quality of engagement, intent, or visitor movement between experiences. FairFlow closes that gap by introducing a more structured way to collect and analyze behavioral data in physical venues.

Instead of stopping at footfall, FairFlow measures:

• where visitors go
• which stands retain attention
• how long they stay
• which journeys lead toward high-intent zones such as finance, booking, or VIP areas

For marketing agencies, this creates a clear competitive advantage. It allows them to deliver measurable offline intelligence, justify campaign decisions with evidence, and recommend new activation strategies based on actual visitor behavior. With the AI-powered Insight Agent, it translates these metrics into actionable answers through natural language, removing the technical friction of data exploration and allowing teams to ask complex behavioral questions without manual data pivoting.

Value Proposition

FairFlow solves three core business problems:

1. Offline activations are difficult to measure beyond attendance.
2. Agencies struggle to prove the business impact of experiential campaigns.
3. Organizers and exhibitors lack a reliable way to connect venue behavior to sponsor value, audience quality, and conversion intent.

The platform addresses these problems through a modern analytics workflow:

• live collection of indoor location events
• stand-level dwell and proximity inference
• reconstruction of visitor journeys across the venue
• analytics APIs and dashboards designed for operations, reporting, and strategic decision-making

Who It Is For

• Marketing agencies that need stronger offline reporting and differentiated strategic value
• Event organizers that need proof of exhibitor performance and audience flow
• Brand and exhibitor teams that need stand-level engagement visibility

What The Product Delivers

• Real-time ingestion of location events from the venue
• Session-aware visitor tracking
• Stand visit inference using configurable proximity rules
• Dwell analysis and repeat-visit measurement
• Transition analysis between stands and key destination areas
• Daily aggregate tables for fast reporting
• Dashboard views for venue overview, stand performance, and visitor journeys
• An AI-assisted analytics query interface

Technical Overview

End-to-end behavioral analytics pipeline

FairFlow is a full data pipeline that converts raw indoor location points into structured analytics products. It handles real-time ingestion, stateful session tracking, and rule-based inference for physical interactions.

The Agentic Analyst: Bridging the "So What?" Gap

While dashboards show what happened, the integrated AI Analyst explains why it matters. By providing a natural language interface over complex behavioral aggregates, stakeholders can:

• Instant Comparisons: "Compare the retention rate between the BMW Lounge and the Tesla Theater."
• Trend Detection: "Which stands saw the highest increase in repeat visitors compared to yesterday?"
• Flow Discovery: "Did people who visited the Audi Studio eventually go to the Financing Desk?" This eliminates the need for manual data exploration, allowing agencies to uncover non-obvious insights in seconds during a client meeting.

A better model for offline measurement

The core innovation is the conversion of physical movement into usable marketing intelligence. The system captures live events, infers visits and dwell, identifies transitions, and materializes summaries that resemble digital funnel analytics for physical spaces.

Clear separation between ingestion, processing, and serving

The platform separates synchronous APIs, persistent storage, background processing, and frontend reporting. That improves reliability, simplifies scaling, and keeps the analytics layer fast to consume.

Explainable inference logic

Stand activity is inferred through explicit proximity and dwell rules rather than opaque heuristics. This makes the output easier to trust and easier to explain to clients or judges in a pitch setting.

Multiple product surfaces from one event stream

The same data foundation supports:

• admin configuration and venue setup
• mobile or device-side event ingestion
• analytics dashboards
• natural-language insight queries

Architecture

flowchart LR
    subgraph Clients
        Mobile[Mobile Tracking Client]
        Admin[Admin and Operations User]
        Dashboard[Analytics Dashboard]
        Analyst[AI Insight User]
    end

    subgraph API["FastAPI Application"]
        Health[Health Endpoints]
        Maps[Admin and Map Configuration APIs]
        Ingest[Location Ingestion API]
        Analytics[Analytics APIs]
        Agent[Agent Query API]
    end

    subgraph Workers["Background Processing"]
        CeleryWorker[Celery Worker]
        CeleryBeat[Celery Beat]
    end

    subgraph Storage
        Postgres[(PostgreSQL)]
        Redis[(Redis)]
        Uploads[(Uploaded Map Files)]
    end

    Mobile --> Ingest
    Admin --> Maps
    Dashboard --> Analytics
    Analyst --> Agent

    Ingest --> Postgres
    Ingest -->|visit and dwell inference| Postgres
    Maps --> Postgres
    Maps --> Uploads
    Maps --> Redis

    Redis --> CeleryWorker
    CeleryBeat --> Redis
    CeleryWorker --> Uploads
    CeleryWorker --> Postgres
    CeleryBeat --> Postgres

    Analytics --> Postgres
    Agent --> Postgres

Loading

Technology Stack

• Backend: FastAPI, SQLAlchemy, Alembic, Pydantic Settings
• Data layer: PostgreSQL, Redis
• Background processing: Celery worker and Celery beat
• Frontend: Next.js, React, TypeScript, TanStack Query
• AI layer: LangChain, LangGraph, Azure OpenAI integration
• Packaging and runtime: Docker Compose

Delivered Capabilities

Backend

• Fair, floor, stand, calibration, and map-upload administration
• Live location-event ingestion
• Dwell and transition inference
• Analytics endpoints for overview, stand performance, transitions, and snapshots
• AI query endpoint for natural-language analytics questions

Data and analytics

• Transactional storage for visitors, sessions, location events, stand visits, and transitions
• Serving tables for daily stand and fair aggregates
• Snapshot materialization for dashboard consumption
• Scheduled background jobs for analytics refresh

Frontend

• Venue overview dashboard
• Stand performance dashboard
• Visitor journey and transition analysis
• Snapshot inspection view
• AI insight terminal

Repository Structure

app/
  api/              FastAPI routes and dependencies
  core/             Settings and logging
  db/               SQLAlchemy engine and session management
  jobs/             Background job orchestration
  models/           ORM entities
  schemas/          Pydantic request and response models
  services/         Dwell, analytics, map ingestion, and AI logic
  tasks/            Celery task definitions
frontend/
  src/app/          Next.js application routes
  src/components/   Dashboard and agent UI
  src/lib/          API client, hooks, constants, and shared types
scripts/
  seed_tunisian_demo.py   Demo seed for the showroom dataset
  wait_for_db.py          Database readiness helper
alembic/
  versions/         Database migrations

Running With Docker

Prerequisites

• Docker
• Docker Compose

Start the backend services

docker compose up -d --build

This starts:

• PostgreSQL on localhost:5432
• Redis on localhost:6379
• FastAPI on localhost:8000
• Celery worker
• Celery beat

Check health

curl http://localhost:8000/health/live
curl http://localhost:8000/health/ready

Seed the demo fair

docker exec out-of-brief-api-1 python scripts/seed_tunisian_demo.py

Start the frontend

cd frontend
pnpm install
pnpm dev

The dashboard runs at:

http://localhost:3000

The frontend targets this backend by default:

http://localhost:8000/v1

Rebuild after backend changes

The backend source code is copied into the Docker image during build, so Python changes require a rebuild:

docker compose up -d --build api celery-worker celery-beat

If only the API changed:

docker compose up -d --build api

Running Without Docker

Prerequisites

• Python 3.13
• PostgreSQL 16 or later
• Redis 7 or later
• Node.js 20 or later
• pnpm

Backend setup

python -m venv .venv
pip install -r requirements.txt
cp .env.example .env
alembic upgrade head
uvicorn app.main:app --host 0.0.0.0 --port 8000

Run worker:

celery -A app.celery_app.celery_app worker --loglevel=INFO

Run beat:

celery -A app.celery_app.celery_app beat --loglevel=INFO

Seed demo data:

python scripts/seed_tunisian_demo.py

Frontend setup

cd frontend
pnpm install
pnpm dev

Environment Configuration

Copy .env.example to .env and adjust values as needed.

Important variables:

• DATABASE_URL
• REDIS_URL
• CELERY_BROKER_URL
• CELERY_RESULT_BACKEND
• UPLOAD_DIR
• AUTH_ADMIN_TOKEN
• AUTH_MOBILE_TOKEN
• AUTH_ANALYTICS_TOKEN
• NEXT_PUBLIC_API_URL for frontend override when needed

Authentication Model

The current MVP uses simple bearer tokens mapped to roles:

• admin-token-dev
• mobile-token-dev
• analytics-token-dev

These roles separate:

• administration and venue configuration
• device-side event ingestion
• analytics and dashboard access

Key API Surfaces

Health

• GET /health/live
• GET /health/ready

Admin

• POST /v1/admin/fairs
• POST /v1/admin/floors
• POST /v1/admin/maps/upload
• POST /v1/admin/fairs/{fair_id}/calibrations
• POST /v1/admin/fairs/{fair_id}/stands
• PATCH /v1/admin/stands/{stand_id}

Mobile ingestion

• POST /v1/mobile/location-events

Analytics

• GET /v1/analytics/fairs/{fair_id}/overview?day=YYYY-MM-DD
• GET /v1/analytics/fairs/{fair_id}/stands/{stand_id}?day=YYYY-MM-DD
• GET /v1/analytics/fairs/{fair_id}/transitions?day=YYYY-MM-DD
• GET /v1/analytics/fairs/{fair_id}/snapshots/{day}
• POST /v1/analytics/fairs/{fair_id}/agent-query

Demo Dataset

The repository includes a pitch-ready showroom dataset for Tunisia Auto Showcase 2026 at Parc des Expositions du Kram.

It contains named stands such as:

• BMW Performance Lounge
• Mercedes-Benz Pavilion
• Audi Sport Studio
• Porsche Experience Bay
• Toyota Hybrid Hub
• Kia EV Garage
• Tesla Tech Theater
• Financing and Insurance Desk
• Test Drive Booking
• VIP Buyer Lounge

This dataset is designed to produce realistic:

• premium-brand comparison behavior
• EV and hybrid exploration paths
• high-intent conversion flows
• readable stand names in the dashboard instead of anonymous zone identifiers

Demo Flow

For a live presentation, the clearest showcase sequence is:

• start with Venue Overview to establish traffic and engagement scale
• move to Stand Performance to compare named exhibitors
• open Visitor Journey to show movement between brands and conversion areas
• use Query Insights to ask a natural-language question about dwell, transitions, or intent

Quality Checks

Backend tests:

pytest -q

Frontend lint:

cd frontend
pnpm lint