# omkargade04/sentinel-agent architecture

> Architecture diagram of the GitHub repository omkargade04/sentinel-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/omkargade04/sentinel-agent
- Repository: https://github.com/omkargade04/sentinel-agent

## Overview

##### Project Type & Purpose
- Sentinel is a backend service exposing a REST API (FastAPI) that integrates with GitHub to fetch and review pull requests.
- It persists data in a PostgreSQL database (via Supabase) and likely calls out to an AI model for bug detection.
- There is no user‐facing frontend—only API endpoints and background processing.

##### File Structure & Map to Layers
- Entry point: `src/main.py` boots up the FastAPI application.
- API Layer (presentation):
- `src/api/fastapi/middlewares/…` (authentication, GitHub webhook auth, request logging)
- `src/api/fastapi/routes/…` (health, user, repository, GitHub, pull‐request endpoints)
- Business Logic Layer (application):
- `src/services/…` (github_service, installation_service, repository_service, user_service)
- Helpers and domain logic live here.
- Data Layer (infrastructure):
- `src/models/db/…` (ORM definitions or table schemas for all tables)
- `src/models/schemas/…` (Pydantic models for request/response validation)
- `src/core/database.py` (DB session management)
- `src/core/supabase_client.py` (Supabase wrapper)
- External Integrations:
- GitHub API (via `services/github`)
- AI code‐review engine (implied)
- Support & Ops:
- SQL migrations (`src/migrations/init.sql`)
- Docker (Dockerfile, docker-compose.yaml)
- CI/CD (GitHub Actions in `.github/workflows/unit-tests.yaml`)

##### README Insights
- Clarifies it tracks PRs, reviews them, detects bugs.
- Installation steps confirm it runs as a standalone Python service.

a. Main Components to Represent
1. GitHub Webhooks & REST calls
- Incoming events (PR opened, PR updated)
2. API Gateway / FastAPI Server
- Middlewares (Auth, Logging)
- Routers (Route handlers)
3. Service Layer
- GitHubService, RepositoryService, UserService
4. External AI Engine
- (If using OpenAI or custom model)
5. Database
- PostgreSQL (Supabase)
6. CI/CD & Deployment
- GitHub Actions
- Docker & Docker Compose
b. Relationships & Data Flows
- Data flows back: Service → Response → Route → GitHub API (e.g., posting review comments).
c. Architectural Patterns
- Layered (Presentation → Application → Infrastructure)
- Hexagonal / Ports & Adapters: abstractions in `core/` and `services/`.
d. Key Technologies
- FastAPI, Pydantic
- SQLAlchemy or Supabase client
- PostgreSQL
- Docker, GitHub Actions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    GitHubAPI["GitHub Webhooks & API"]:::external
    AICodeReview["AI Code-Review Engine"]:::external

    %% API Layer
    subgraph "API Layer"
        MainApp["FastAPI Entry Point\nsrc/main.py"]:::api
        AuthMW["Authentication Middleware"]:::api
        GHAuthMW["GitHub Webhook Auth Middleware"]:::api
        LogMW["Request Logging Middleware"]:::api
        HealthRoute["Health Check Route"]:::api
        UserRoute["User Routes"]:::api
        RepoRoute["Repository Routes"]:::api
        GHRoute["GitHub Routes"]:::api
    end

    %% Service Layer
    subgraph "Service Layer"
        GitHubService["GitHub Service"]:::service
        GHHelpers["GitHub Helpers"]:::service
        InstallService["GitHub Installation Service"]:::service
        RepoService["Repository Service"]:::service
        RepoHelpers["Repository Helpers"]:::service
        UserService["User Service"]:::service
        UserHelpers["User Helpers"]:::service
    end

    %% Data Layer
    subgraph "Data Layer"
        ORMModels["Database Models (src/models/db/)"]:::db
        PydSchemas["Pydantic Schemas (src/models/schemas/)"]:::db
        PostgresDB["PostgreSQL (Supabase)"]:::db
    end

    %% Core Infrastructure
    subgraph "Core Infrastructure"
        DBSession["Database Session Management"]:::core
        SupabaseClient["Supabase Client Wrapper"]:::core
        Config["Configuration"]:::core
    end

    %% Utilities
    subgraph "Utilities"
        ExceptionUtil["Exception Handling"]:::util
        LogUtil["Logging Utilities"]:::util
    end

    %% Support & Ops
    subgraph "Support & Ops"
        Migrations["SQL Migrations"]:::ops
        DockerfileNode["Dockerfile"]:::ops
        DockerCompose["docker-compose.yaml"]:::ops
        CIWorkflow["CI/CD Workflow"]:::ops
    end

    %% Connections
    GitHubAPI -->|webhook/event| MainApp
    MainApp --> AuthMW
    AuthMW --> GHAuthMW
    GHAuthMW --> LogMW
    LogMW --> HealthRoute
    LogMW --> UserRoute
    LogMW --> RepoRoute
    LogMW --> GHRoute

    HealthRoute -->|calls| UserService
    UserRoute -->|calls| UserService
    RepoRoute -->|calls| RepoService
    GHRoute -->|calls| GitHubService

    GitHubService --> GHHelpers
    InstallService -->|calls| GitHubService
    RepoService --> RepoHelpers
    UserService --> UserHelpers

    GitHubService -->|reads/writes| PostgresDB
    RepoService -->|reads/writes| PostgresDB
    UserService -->|reads/writes| PostgresDB

    GitHubService -->|calls| GitHubAPI
    GitHubService -->|calls| AICodeReview

    DBSession --> PostgresDB
    SupabaseClient --> PostgresDB

    MainApp --> DBSession
    MainApp --> SupabaseClient

    MainApp --> Config
    ServiceLayerConfig(Config):::core

    ExceptionUtil -.-> MainApp
    LogUtil -.-> MainApp

    CIWorkflow -->|build & test| DockerfileNode
    DockerfileNode -->|compose| DockerCompose
    DockerCompose --> MainApp

    %% Click Events
    click MainApp "https://github.com/omkargade04/sentinel-agent/blob/main/src/main.py"
    click AuthMW "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/middlewares/auth.py"
    click GHAuthMW "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/middlewares/github.py"
    click LogMW "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/middlewares/logging.py"
    click HealthRoute "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/routes/health.py"
    click UserRoute "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/routes/user.py"
    click RepoRoute "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/routes/repository.py"
    click GHRoute "https://github.com/omkargade04/sentinel-agent/blob/main/src/api/fastapi/routes/github.py"
    click GitHubService "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/github/github_service.py"
    click GHHelpers "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/github/helpers.py"
    click InstallService "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/github/installation_service.py"
    click RepoService "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/repository/repository_service.py"
    click RepoHelpers "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/repository/helpers.py"
    click UserService "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/users/user_service.py"
    click UserHelpers "https://github.com/omkargade04/sentinel-agent/blob/main/src/services/users/helpers.py"
    click ORMModels "https://github.com/omkargade04/sentinel-agent/tree/main/src/models/db/"
    click PydSchemas "https://github.com/omkargade04/sentinel-agent/tree/main/src/models/schemas/"
    click DBSession "https://github.com/omkargade04/sentinel-agent/blob/main/src/core/database.py"
    click SupabaseClient "https://github.com/omkargade04/sentinel-agent/blob/main/src/core/supabase_client.py"
    click Config "https://github.com/omkargade04/sentinel-agent/blob/main/src/core/config.py"
    click Migrations "https://github.com/omkargade04/sentinel-agent/blob/main/src/migrations/init.sql"
    click DockerfileNode "https://github.com/omkargade04/sentinel-agent/tree/main/Dockerfile"
    click DockerCompose "https://github.com/omkargade04/sentinel-agent/blob/main/docker-compose.yaml"
    click CIWorkflow "https://github.com/omkargade04/sentinel-agent/blob/main/.github/workflows/unit-tests.yaml"
    click ExceptionUtil "https://github.com/omkargade04/sentinel-agent/blob/main/src/utils/exception.py"
    click LogUtil "https://github.com/omkargade04/sentinel-agent/blob/main/src/utils/logging/default.py"

    %% Styles
    classDef api fill:#ade8f4,stroke:#023047,color:#000;
    classDef service fill:#caf0f8,stroke:#0077b6,color:#000;
    classDef db fill:#ffc8dd,stroke:#d00000,color:#000;
    classDef core fill:#ffec99,stroke:#ffb703,color:#000;
    classDef external fill:#e0fbfc,stroke:#168aad,color:#000;
    classDef ops fill:#d8f3dc,stroke:#40916c,color:#000;
    classDef util fill:#f8edeb,stroke:#a41623,color:#000;
```
