akshat3144/synapse

1. System shape

Synapse is a two-tier application: a Python FastAPI backend that continuously ingests pharma signals and generates intelligence, and a Next.js frontend that presents dashboards, entity views, alerts, and strategic briefs. The backend owns all business logic and data persistence; the frontend is a presentation layer that consumes API and WebSocket feeds.

2. Primary data flow

External sources feed the backend ingestion services: openFDA (recalls, adverse events, drug labels), NewsAPI (pharma news), and ClinicalTrials.gov (trial updates). Those raw signals are normalized into event records, stored, broadcast live, and then used as input for clustering and brief generation.

3. Backend layering

The backend is split into a few clear boundaries:

- services/ for source polling and intelligence processing

- routes/ for HTTP API endpoints

- store.py / store_supabase.py for persistence

- scheduler.py for recurring jobs

- ws_manager.py for real-time push updates

- models.py for shared data contracts

4. Ingestion services

Each source has its own monitor:

- fda_monitor.py for recalls and adverse events

- label_monitor.py for label/SPL changes

- news_crawler.py for NewsAPI and event classification

- clinical_trials.py for trial updates

These services produce a common event shape so downstream logic does not depend on source-specific formats.

5. Intelligence pipeline

The agentic core lives mainly in brief_generator.py and summarizer.py. Events are clustered by entity overlap into signal clusters, severity is assigned, and then unbriefed clusters are turned into strategic briefs. This is the main “analysis” boundary of the system, separate from raw ingestion and separate from presentation.

6. Agentic scheduling

scheduler.py orchestrates two kinds of background work: frequent source polling and the autonomous scan loop. The scan loop runs every 20 minutes, finds interesting clusters, skips recently briefed entities, and generates up to a few new briefs per cycle. There is also a manual trigger path via API for on-demand polling or brief generation.

7. Persistence boundary

Storage is abstracted behind the store layer. store_supabase.py persists to Supabase/PostgreSQL using a schema defined in supabase_schema.sql, while the app can fall back to an in-memory store if Supabase credentials are absent. This means the rest of the code treats storage as a stable interface rather than depending directly on database details.

8. Data model

models.py defines the shared domain objects used across ingestion, API, and UI: events, alerts, entities, signal clusters, briefs, SWOT/Porter/GTM structures, and source status. This keeps the API payloads and frontend TypeScript types aligned with the backend domain model.

9. API surface

The FastAPI routes are organized by concern:

- events.py for event listing, detail, stats, search, trends

- alerts.py for alert rules and dismissals

- entities.py for tracked entities and entity analysis

- briefs.py for briefs, clusters, and scan/generate actions

- sources.py for source health

These routes expose both operational data and derived intelligence to the frontend.

10. Real-time delivery

ws_manager.py plus the /ws/feed endpoint provide a live event feed. New ingested events are pushed to connected clients, so the UI can update without polling. This is a key architectural boundary between batch/background processing and interactive display.

11. Frontend structure

The frontend is a Next.js App Router application. Page routes map directly to the backend concepts: dashboard, briefs, entities, events, alerts, and search. UI components are split into layout shell components, dashboard widgets, and shared event/status badges. The frontend is clearly a consumer of backend intelligence rather than a source of business logic.

12. Frontend data access

frontend/lib/api.ts centralizes REST calls, websocket.ts handles live feed connections and reconnects, and hooks.ts exposes reusable data hooks for pages/components. types.ts mirrors backend models so the dashboard, detail pages, and charts can render structured intelligence consistently.

13. Operational behavior

On startup, the backend immediately begins polling source APIs and scheduling the agentic scan. The system also exposes diagnostics and source-status endpoints so operators can see API key health, poll times, and scheduler state. That makes the backend both the runtime engine and the observability point for the app.

14. Important architectural takeaway

The core architecture is an event-to-intelligence pipeline: external sources → normalized events → persistence/live feed → clustering and brief generation → API + WebSocket delivery → frontend analytics and drill-down views. The main design boundaries are source adapters, intelligence processing, storage abstraction, and the presentation layer.