Project Architecture Map

This document provides a complete map of the SafeCall project for AI assistants. Use it to quickly understand what lives where and how components connect.

Monorepo Layout

safecall/
├── lib/                    # Shared TypeScript library
│   └── src/                # Schemas, DB, HTTP, MQTT, JWT, types
├── server/                 # Bun backend (HTTP API, WebSocket, MQTT, tracking)
│   ├── src/                # Application source
│   │   ├── routes/         # HTTP and WebSocket route handlers
│   │   └── algs/           # Tracking algorithms
│   ├── migrations/         # SQLite migration files (001-029)
│   └── tests/              # Server tests
│       └── api/            # API endpoint tests
├── web/                    # Web frontend (vanilla TypeScript SPA)
│   └── src/
│       ├── pages/          # Page modules (dashboard, login, maps, zones, etc.)
│       ├── lib/            # Contracts, socket, canvas, util
│       └── templates/      # HTML templates grouped by feature
├── mobile/                 # Flutter app (indoor navigation)
│   └── lib/
│       ├── screens/        # UI screens
│       ├── services/       # API client, BLE scanner
│       ├── models/         # Data models
│       ├── core/           # Graph, positioning
│       └── game/           # Flame map renderer
├── scripts/                # Build, release, install, CLI tooling
│   └── cli/                # CLI subcommands
├── docs/                   # This documentation site (VitePress)
└── main.config.json        # Central configuration file

Component Dependencies

lib/ ──────────────► server/ ──────► MQTT Broker
  │                    │                │
  │                    ├─► SQLite       │
  │                    ├─► Zabbix       │
  │                    └─► Web UI       │
  │                        (embedded)   │
  │                                     │
  └──────────────────► web/             │
                        │               │
                        └─► Browser     │
                                        │
mobile/ ──────────────► Server API ◄────┘
  │
  ├─► BLE Beacons (direct scan)
  └─► Local SQLite (offline cache)

Key Data Flows

1. Beacon Tracking (Server-Side)

BLE Beacon → Gateway (MQTT) → server/mqtt.ts → events.ts → tracking.ts → WebSocket → Web UI

2. Indoor Navigation (Mobile)

QR Code → ApiClient → Server API → NavigationBundle → Graph + BLE → Position → Flame Map

3. Bridge to Zabbix

MQTT → server/mqtt.ts → bridge.ts → ZabbixSender → Zabbix Server

4. Web Build Embedding

web/src/ → Bun.build → web/build/ → generate-embeds.ts → server/static_embeds.ts → Binary

Database Schema (Key Tables)

Table	Foreign Keys	Purpose
users	—	User accounts
locations	—	Physical buildings
beacons	location_id	BLE beacons
gateways	location_id, map_id	BLE gateways
maps	location_id	Floor map images
zones	map_id	Zones on maps
zone_connections	zone_id × 2	Zone adjacency
floors	location_id	Navigation floors
nodes	floor_id	Graph nodes
edges	node_id × 2	Graph edges
navigation_tokens	location_id	Mobile access tokens
beacon_events	beacon_id, zone_id	Panic/SOS events
logs	—	System logs

Configuration Prefix Convention

All config keys in main.config.json use a service prefix:

• server_* — Server settings
• bridge_* — Bridge/Zabbix settings

The web frontend has no config keys — it reads them from the build script.