# tarek-gritli/lynx architecture

> Architecture diagram of the GitHub repository tarek-gritli/lynx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tarek-gritli/lynx
- Repository: https://github.com/tarek-gritli/lynx

## Overview

This repository is a two-tier application: a Python backend API and a React frontend SPA, packaged and deployed separately but designed to work together as one product called Lynx.

#### 1) High-level system shape

The architecture centers on three major boundaries:

1. **Browser/UI layer**  
   The frontend is a single-page application that handles landing/authenticated views, dashboards, review history, and settings.

2. **Backend API layer**  
   A FastAPI application exposes REST endpoints for authentication, dashboard data, notifications, templates, settings, and webhook intake.

3. **External integrations layer**  
   The backend talks to:
   - **GitHub** and **GitLab** for PR/MR events and repository metadata
   - **LLM providers** such as OpenAI, Gemini, and Claude for code review generation
   - A **relational database** for persistence
   - Optional **notification delivery** mechanisms handled through backend services

The repo is optimized for self-hosting: code stays on your infrastructure, and the user supplies their own LLM API keys.

---

#### 2) Backend architecture

##### Runtime and framework
The backend is a **Python 3.12+ FastAPI** service. It is organized into clear application layers:

- **`app/api`**: HTTP surface area
- **`app/api/services`**: business logic and external integrations
- **`app/core`**: config and database wiring
- **`app/models.py`**: persistent domain models
- **`app/alembic`**: schema migrations
- **`app/utils`**: reusable support functions
- **`app/prompts.py`**: LLM prompt content/structure

##### API surface
The backend routes are split by domain:

- **`auth.py`**: user authentication, likely OAuth-based
- **`dashboard.py`**: stats and overview data for the UI
- **`notifications.py`**: notification retrieval/status
- **`settings.py`**: account/app configuration, including API keys
- **`templates.py`**: template CRUD and default template management
- **`webhooks.py`**: inbound PR/MR webhook events from GitHub/GitLab

This separation is important for diagramming because it shows the backend is not one generic API, but a set of domain-specific endpoints with different consumers:
- the frontend calls dashboard/settings/templates/notifications
- GitHub/GitLab call webhooks
- auth routes support browser login/session flows

##### Service layer
The `services` package is where the real orchestration happens:

- **`github.py` / `gitlab.py`**  
  Platform adapters for repository providers. These likely normalize PR/MR data, comments, diffs, and webhook payloads into a shared internal review flow.

- **`review.py`**  
  Central review orchestration. This is likely where a webhook or manual trigger becomes a review job: gathering changed files, generating prompts, calling LLMs, assembling the final review, and persisting results.

- **`llm.py`**  
  Provider abstraction over OpenAI, Gemini, and Claude. This suggests the system can switch vendors without changing upstream business logic.

- **`validation.py`**  
  Pre-review checks and guardrails. This likely filters unsupported file types, rejects invalid webhook payloads, or ensures review eligibility.

- **`notifications.py`**  
  Creates and dispatches notifications after reviews or on important events.

This service layer is the main “processing engine” of the backend.

##### Data and persistence
The presence of Alembic migrations and `models.py` indicates a relational database, most likely PostgreSQL in production, though the exact engine is not shown in the tree.

The schema history suggests the app stores at least these categories of data:

- reviews and review tracking
- PR/MR metadata
- notification records
- templates
- LLM model/provider configuration
- review status and error fields
- cost calculation data

The migrations imply the system evolved from basic tables to a more complete review workflow with tracking, errors, notifications, templates, and LLM provider records.

##### Security-sensitive utilities
Several utility modules are architectural signals:

- **`crypto.py`**  
  Fernet encryption is mentioned in the README. This module likely encrypts stored API keys and other secrets before persistence.

- **`file_filter.py`**  
  Filters which files are included in a review, helping constrain what is sent to the LLM and what is ignored.

- **`cost.py`**  
  Tracks or estimates review cost, probably based on tokens or provider pricing.

These are important because they define system boundaries around sensitive data and LLM usage.

##### Backend entrypoints and packaging
The backend has both `app/main.py` and `app/api/main.py`, suggesting one is the service entrypoint and the other is the FastAPI app composition module. It is containerized via `backend/Dockerfile`, with Alembic configured for migrations.

---

#### 3) Frontend architecture

##### Runtime and framework
The frontend is a **TypeScript React SPA** built with **Vite**. The file structure indicates a modern componentized UI architecture using:

- route-based code organization
- shared UI primitives
- hooks for data fetching/state
- a query client for server state

##### Routing and page boundaries
The route tree is split into two major shells:

- **Unauthenticated routes**
  - landing page
  - auth error page

- **Authenticated routes**
  - dashboard
  - history list
  - review detail view
  - settings

This is a key diagram boundary: the frontend has a public marketing/auth surface and a private application surface.

##### UI subsystems
The component tree reflects the product domains:

- **Landing components**: hero, feature cards, terminal demo, footer, trusted-by
- **Dashboard components**: KPI cards, LLM provider cards, recent reviews
- **History components**: filters, pagination, history header, detail view
- **Settings components**:
  - API configuration
  - templates management
  - webhook configuration
- **Navigation components**: sidebar, mobile nav, user menu, notification panel

The UI is not generic; it is built around the review workflow and configuration of a code-review product.

##### Frontend state and data access
The hooks and library structure show how the frontend talks to the backend:

- **`lib/api.ts`**: API client abstraction
- **`lib/query-client.ts`**: shared server-state cache
- **`hooks/use-auth.ts`**: authentication state
- **`hooks/use-reviews.ts`**, `use-stats.ts`, `use-templates.ts`, `use-notifications.ts`, `use-api-keys.ts`: domain fetch hooks
- **`use-clipboard.ts`**, `use-mobile.ts`: local UI concerns

This suggests the frontend is mostly a thin consumer of backend REST APIs, with server state managed centrally and cached for dashboard/history/settings views.

---

#### 4) Core end-to-end data flows

##### A. Review event flow
This is the most important architecture path.

1. A PR or MR event happens in **GitHub or GitLab**
2. The provider sends a **webhook** to the backend
3. The backend verifies the request and normalizes the payload through the provider service
4. The review pipeline filters files and validates the request
5. The review service builds prompts from templates and review context
6. The LLM service sends the prompt to the configured provider using the user’s encrypted API key
7. The generated review is stored in the database
8. Notifications are created
9. The frontend dashboard/history pages retrieve and display the result

This is the main “data plane” of the product.

##### B. Settings/configuration flow
1. The authenticated user opens settings in the frontend
2. The frontend submits configuration changes to backend settings/template routes
3. The backend encrypts sensitive values such as API keys
4. Configuration is persisted in the database
5. The review pipeline later consumes that configuration when processing reviews

This flow is important because it defines how runtime behavior changes without code changes.

##### C. History and review-detail flow
1. The frontend requests paginated review history
2. Backend returns stored review summaries and statuses
3. The user opens a review detail page
4. Backend returns full review content, metadata, cost, errors, and status tracking

This is a read-heavy flow driven by the persistent review store.

##### D. Notification flow
1. Reviews or important events are recorded
2. Notification service writes notification records
3. Frontend notification panel fetches recent notifications
4. User interaction may update notification state/read status

---

#### 5) Key external boundaries

##### Git provider boundary
The system supports both:
- **GitHub** including app-based integration
- **GitLab** including cloud and self-hosted

That means the backend must normalize different webhook formats and API behaviors into a common review model.

##### LLM provider boundary
The backend supports multiple providers:
- OpenAI
- Gemini
- Claude

This is abstracted behind the `llm` service, which is a strong architectural boundary. The app is designed to avoid hard-coupling the review pipeline to any single vendor.

##### Secret handling boundary
Encrypted API keys and OAuth/session data make security a first-class boundary. The README explicitly calls out:
- OAuth 2.0
- Fernet-encrypted API keys
- webhook signature verification

So any diagram should show a trust boundary around inbound webhooks and a separate secure storage boundary for credentials.

---

#### 6) Deployment and infrastructure shape

The repo includes Docker support for:
- **backend**
- **frontend**
- orchestration via **docker-compose**
- optional **Traefik** reverse proxy for production routing and TLS

There are two deployment modes worth showing in a diagram:

1. **Local development**
   - frontend on port 5173
   - backend on port 8000
   - separate containers via dev compose

2. **Production**
   - frontend and backend behind a domain
   - optional Traefik as edge proxy
   - environment-driven configuration for API base URLs, cookies, and TLS

The architecture is therefore containerized and proxy-friendly, but not tightly coupled to a particular cloud provider.

---

#### 7) What to emphasize in an architecture diagram

If you are drawing this system, the most important boxes and arrows are:

- Browser/UI SPA
- FastAPI backend API
- Webhook ingress from GitHub/GitLab
- Review orchestration service
- LLM provider adapters
- Database / persistence
- Notification subsystem
- Secure secret storage/encryption boundary
- Authentication/session boundary
- Reverse proxy / TLS edge in production

The key message is that Lynx is a **self-hosted code review orchestration platform**: the frontend is mostly a configuration and observability layer, while the backend performs the real business work of ingesting repository events, generating AI reviews, persisting outcomes, and returning them to the UI.

Main entry points: [`backend/app/main.py`](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/main.py) (FastAPI App), [`frontend/src/App.tsx`](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/App.tsx) (React SPA), [`backend/app/core/database.py`](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/core/database.py) (Database), [`backend/app/api/services/review.py`](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/services/review.py) (Review Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Frontend SPA"
  browser(("Browser<br/>user client"))
  spa["React SPA<br/>Vite app<br/>[App.tsx]"]
  landing["Public UI<br/>unauthenticated route<br/>[landing.tsx]"]
  dashboard["Dashboard<br/>authenticated route<br/>[dashboard.tsx]"]
  history["Review History<br/>authenticated route<br/>[index.tsx]"]
  settings["Settings<br/>authenticated route<br/>[settings.tsx]"]
  api_client["API Client<br/>frontend data layer<br/>[api.ts]"]
end

subgraph "Backend API"
  backend_api["FastAPI App<br/>python service<br/>[main.py]"]
  auth_routes["Auth API<br/>route module<br/>[auth.py]"]
  dashboard_routes["Dashboard API<br/>route module<br/>[dashboard.py]"]
  notifications_routes["Notifications API<br/>route module<br/>[notifications.py]"]
  settings_routes["Settings API<br/>route module<br/>[settings.py]"]
  templates_routes["Templates API<br/>route module<br/>[templates.py]"]
  webhooks_routes["Webhook API<br/>route module<br/>[webhooks.py]"]
  review_service{{"Review Engine<br/>orchestration service<br/>[review.py]"}}
  provider_adapters["Git Adapters<br/>integration service<br/>[github.py]"]
  llm_service["LLM Gateway<br/>provider abstraction<br/>[llm.py]"]
  notifications_service["Notify Service<br/>[notifications.py]"]
  validation_service["Validation<br/>guardrail service<br/>[validation.py]"]
  db[("Database<br/>relational persistence<br/>[database.py]")]
  crypto["Secret Crypto<br/>security utility<br/>[crypto.py]"]
end

subgraph "External Systems"
  github(("GitHub<br/>external git provider"))
  gitlab(("GitLab<br/>external git provider"))
  llm_providers(("LLM Providers<br/>external ai services"))
end

browser -->|"uses"| spa
spa -->|"calls"| api_client
api_client -->|"HTTP"| backend_api
spa -->|"routes to"| landing
spa -->|"routes to"| dashboard
spa -->|"routes to"| history
spa -->|"routes to"| settings
backend_api -->|"mounts"| auth_routes
backend_api -->|"mounts"| dashboard_routes
backend_api -->|"mounts"| notifications_routes
backend_api -->|"mounts"| settings_routes
backend_api -->|"mounts"| templates_routes
backend_api -->|"mounts"| webhooks_routes
webhooks_routes -->|"normalizes"| provider_adapters
provider_adapters -->|"receives from"| github
provider_adapters -->|"receives from"| gitlab
webhooks_routes -->|"checks"| validation_service
validation_service -->|"gates"| review_service
review_service -->|"generates with"| llm_service
llm_service -->|"invokes"| llm_providers
review_service -->|"persists"| db
notifications_service -->|"writes"| db
review_service -->|"emits"| notifications_service
settings_routes -->|"encrypts"| crypto
crypto -->|"stores in"| db
dashboard_routes -->|"reads"| db
notifications_routes -->|"reads"| db
settings_routes -->|"reads/writes"| db
templates_routes -->|"reads/writes"| db

click spa "https://github.com/tarek-gritli/lynx/blob/main/frontend/src/App.tsx"
click landing "https://github.com/tarek-gritli/lynx/blob/main/frontend/src/routes/_unauthenticated/landing.tsx"
click dashboard "https://github.com/tarek-gritli/lynx/blob/main/frontend/src/routes/_authenticated/dashboard.tsx"
click history "https://github.com/tarek-gritli/lynx/blob/main/frontend/src/routes/_authenticated/history/index.tsx"
click settings "https://github.com/tarek-gritli/lynx/blob/main/frontend/src/routes/_authenticated/settings.tsx"
click api_client "https://github.com/tarek-gritli/lynx/blob/main/frontend/src/lib/api.ts"
click backend_api "https://github.com/tarek-gritli/lynx/blob/main/backend/app/main.py"
click auth_routes "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/routes/auth.py"
click dashboard_routes "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/routes/dashboard.py"
click notifications_routes "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/routes/notifications.py"
click settings_routes "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/routes/settings.py"
click templates_routes "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/routes/templates.py"
click webhooks_routes "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/routes/webhooks.py"
click review_service "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/services/review.py"
click provider_adapters "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/services/github.py"
click llm_service "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/services/llm.py"
click notifications_service "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/services/notifications.py"
click validation_service "https://github.com/tarek-gritli/lynx/blob/main/backend/app/api/services/validation.py"
click db "https://github.com/tarek-gritli/lynx/blob/main/backend/app/core/database.py"
click crypto "https://github.com/tarek-gritli/lynx/blob/main/backend/app/utils/crypto.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class browser,spa,landing,dashboard,history,settings,api_client toneBlue
class backend_api,auth_routes,dashboard_routes,notifications_routes,settings_routes,templates_routes,webhooks_routes,review_service,provider_adapters,llm_service,notifications_service,validation_service,db,crypto toneAmber
class github,gitlab,llm_providers toneMint
```

## Components

### Frontend SPA

React/Vite client and its route-level UI

- **Browser**: user client · End-user entry point for the Lynx SPA
- [React SPA](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/App.tsx): Vite app · Single-page application that renders public and authenticated views · `frontend/src/App.tsx`
- [Public UI](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/routes/_unauthenticated/landing.tsx): unauthenticated route · Landing and auth-error screens · `frontend/src/routes/_unauthenticated/landing.tsx`
- [Dashboard](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/routes/_authenticated/dashboard.tsx): authenticated route · Overview page for review activity and health · `frontend/src/routes/_authenticated/dashboard.tsx`
- [Review History](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/routes/_authenticated/history/index.tsx): authenticated route · Paginated review list and detail views · `frontend/src/routes/_authenticated/history/index.tsx`
- [Settings](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/routes/_authenticated/settings.tsx): authenticated route · API keys, templates, and webhook configuration · `frontend/src/routes/_authenticated/settings.tsx`
- [API Client](https://github.com/tarek-gritli/lynx/blob/HEAD/frontend/src/lib/api.ts): frontend data layer · Shared HTTP client and query cache used by hooks · `frontend/src/lib/api.ts`

### Backend API

FastAPI application, services, and persistence

- [FastAPI App](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/main.py): python service · Backend application composition and HTTP entrypoint · `backend/app/main.py`
- [Auth API](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/routes/auth.py): route module · Login and session-related endpoints · `backend/app/api/routes/auth.py`
- [Dashboard API](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/routes/dashboard.py): route module · Statistics and overview endpoints for the UI · `backend/app/api/routes/dashboard.py`
- [Notifications API](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/routes/notifications.py): route module · Notification retrieval and status endpoints · `backend/app/api/routes/notifications.py`
- [Settings API](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/routes/settings.py): route module · Configuration and API key endpoints · `backend/app/api/routes/settings.py`
- [Templates API](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/routes/templates.py): route module · Template CRUD and default-template management · `backend/app/api/routes/templates.py`
- [Webhook API](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/routes/webhooks.py): route module · Inbound PR/MR events from git providers · `backend/app/api/routes/webhooks.py`
- [Review Engine](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/services/review.py): orchestration service · Coordinates file selection, prompt building, LLM calls, and persistence · `backend/app/api/services/review.py`
- [Git Adapters](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/services/github.py): integration service · Normalizes GitHub and GitLab payloads and repository data · `backend/app/api/services/github.py`
- [LLM Gateway](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/services/llm.py): provider abstraction · Unified access to OpenAI, Gemini, and Claude · `backend/app/api/services/llm.py`
- [Notify Service](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/services/notifications.py): service · Creates and dispatches review notifications · `backend/app/api/services/notifications.py`
- [Validation](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/api/services/validation.py): guardrail service · Pre-review checks and request/file eligibility filtering · `backend/app/api/services/validation.py`
- [Database](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/core/database.py): relational persistence · Stores reviews, templates, notifications, settings, and tracking data · `backend/app/core/database.py`
- [Secret Crypto](https://github.com/tarek-gritli/lynx/blob/HEAD/backend/app/utils/crypto.py): security utility · Encrypts stored API keys and other sensitive values · `backend/app/utils/crypto.py`

### External Systems

Git providers, LLMs, and infrastructure boundaries

- **GitHub**: external git provider · Source of webhook events and repository metadata
- **GitLab**: external git provider · Source of webhook events and repository metadata
- **LLM Providers**: external ai services · OpenAI, Gemini, and Claude APIs

## Connections

- Browser → React SPA: uses · User interacts with the web application
- React SPA → API Client: calls · Frontend reads and mutates server state through the shared client
- API Client → FastAPI App: HTTP · REST requests to the FastAPI backend
- React SPA → Public UI: routes to · Public unauthenticated views
- React SPA → Dashboard: routes to · Authenticated overview page
- React SPA → Review History: routes to · Authenticated review history pages
- React SPA → Settings: routes to · Authenticated settings pages
- FastAPI App → Auth API: mounts · Authentication endpoints
- FastAPI App → Dashboard API: mounts · Dashboard endpoints
- FastAPI App → Notifications API: mounts · Notification endpoints
- FastAPI App → Settings API: mounts · Settings endpoints
- FastAPI App → Templates API: mounts · Template management endpoints
- FastAPI App → Webhook API: mounts · Webhook intake endpoints
- Webhook API → Git Adapters: normalizes · Converts provider-specific events into a common review flow
- Git Adapters → GitHub: receives from · GitHub webhook and repository data
- Git Adapters → GitLab: receives from · GitLab webhook and repository data
- Webhook API → Validation: checks · Validates webhook payloads and review eligibility
- Validation → Review Engine: gates · Only valid review jobs proceed to orchestration
- Review Engine → LLM Gateway: generates with · Builds prompts and requests model output
- LLM Gateway → LLM Providers: invokes · Uses configured external LLM provider
- Review Engine → Database: persists · Stores reviews, status, metadata, and costs
- Notify Service → Database: writes · Stores notification records and read state
- Review Engine → Notify Service: emits · Triggers notifications after review events
- Settings API → Secret Crypto: encrypts · Protects stored API keys and secrets
- Secret Crypto → Database: stores in · Encrypted values are persisted in the database
- Dashboard API → Database: reads · Serves summaries and review metrics
- Notifications API → Database: reads · Fetches recent notifications and status
- Settings API → Database: reads/writes · Persists user and application configuration
- Templates API → Database: reads/writes · Manages review templates and defaults
