How tarek-gritli/lynx works
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: main.py FastAPI App · App.tsx React SPA · database.py Database · review.py Review Engine
Components 24
Frontend SPA
React/Vite client and its route-level UI
- Browser · End-user entry point for the Lynx SPA
- React SPA · Single-page application that renders public and authenticated views
frontend/src/App.tsx - Public UI · Landing and auth-error screens
frontend/src/routes/_unauthenticated/landing.tsx - Dashboard · Overview page for review activity and health
frontend/src/routes/_authenticated/dashboard.tsx - Review History · Paginated review list and detail views
frontend/src/routes/_authenticated/history/index.tsx - Settings · API keys, templates, and webhook configuration
frontend/src/routes/_authenticated/settings.tsx - API Client · Shared HTTP client and query cache used by hooks
frontend/src/lib/api.ts
Backend API
FastAPI application, services, and persistence
- FastAPI App · Backend application composition and HTTP entrypoint
backend/app/main.py - Auth API · Login and session-related endpoints
backend/app/api/routes/auth.py - Dashboard API · Statistics and overview endpoints for the UI
backend/app/api/routes/dashboard.py - Notifications API · Notification retrieval and status endpoints
backend/app/api/routes/notifications.py - Settings API · Configuration and API key endpoints
backend/app/api/routes/settings.py - Templates API · Template CRUD and default-template management
backend/app/api/routes/templates.py - Webhook API · Inbound PR/MR events from git providers
backend/app/api/routes/webhooks.py - Review Engine · Coordinates file selection, prompt building, LLM calls, and persistence
backend/app/api/services/review.py - Git Adapters · Normalizes GitHub and GitLab payloads and repository data
backend/app/api/services/github.py - LLM Gateway · Unified access to OpenAI, Gemini, and Claude
backend/app/api/services/llm.py - Notify Service · Creates and dispatches review notifications
backend/app/api/services/notifications.py - Validation · Pre-review checks and request/file eligibility filtering
backend/app/api/services/validation.py - Database · Stores reviews, templates, notifications, settings, and tracking data
backend/app/core/database.py - Secret Crypto · Encrypts stored API keys and other sensitive values
backend/app/utils/crypto.py
External Systems
Git providers, LLMs, and infrastructure boundaries
- GitHub · Source of webhook events and repository metadata
- GitLab · Source of webhook events and repository metadata
- LLM Providers · OpenAI, Gemini, and Claude APIs
Connections 29
- 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