# md-arman-hossain-007/aoble architecture

> Architecture diagram of the GitHub repository md-arman-hossain-007/aoble, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/md-arman-hossain-007/aoble
- Repository: https://github.com/md-arman-hossain-007/aoble

## Overview

1. **Overall shape**
   - This repository is a full-stack AML screening product split into a **Python backend** and a **Next.js frontend**.
   - The backend owns screening logic, data ingestion, persistence, search, and async jobs.
   - The frontend is a dashboard-style analyst UI plus public marketing/auth pages.

2. **Backend application boundary**
   - The backend is organized as a FastAPI-style service under `backend/app`.
   - `app/main.py` is the entrypoint, with domain routers in `app/api/*`.
   - The backend is the primary system of record for screening results, reports, users, cases, notifications, analytics, and integrations.

3. **API surface by business domain**
   - The API layer is split into feature-specific modules such as:
     - `screenings.py` / `screening_v2.py` for screening workflows
     - `bulk.py` for batch screening
     - `case_management*.py` for analyst review/case handling
     - `history_audit.py` for audit trail and activity history
     - `analytics.py`, `stats.py`, `monitoring.py` for dashboards and operational metrics
     - `auth.py`, `users.py`, `admin.py` for identity and administration
     - `billing.py`, `compliance.py`, `integrations.py`, `notifications.py`, `external_search.py`
   - This structure suggests a modular monolith where each API module maps to a distinct product capability.

4. **Core backend services and boundaries**
   - `app/services/*` contains the business logic behind the APIs, including screening, analytics, case management, search, web search, email, reporting, monitoring, notification delivery, and AI enhancement.
   - `app/schemas/*` defines request/response contracts.
   - `app/models/*` holds persistence models, indicating a clear separation between transport, business logic, and storage.

5. **Data storage and persistence**
   - `app/db/session.py` indicates a database session layer, almost certainly for PostgreSQL or another relational DB.
   - The presence of migration SQL files (`migrate*.sql`) and entity/user/org fix scripts shows schema evolution is managed outside a heavy ORM-only workflow.
   - The backend stores screening records, users/organizations, cases, audit history, notifications, and analytics-related data in the relational store.

6. **Search and matching**
   - `app/core/elasticsearch.py` and `app/etl/es_indexer.py` indicate Elasticsearch is used as a search/index layer for large screening datasets.
   - Screening is likely a two-step flow: candidate lookup/search against indexed sanctions/watchlist data, then scoring and result persistence in the DB.
   - `app/services/search.py` and `app/services/web_search.py` suggest both internal indexed search and optional external/web search enrichment.

7. **Ingestion and ETL pipeline**
   - The ETL subsystem under `app/etl/*` is responsible for importing and normalizing OpenSanctions-style source data.
   - Main stages appear to be:
     - source registration and download (`source_registry.py`, `downloader.py`)
     - normalization (`normalizer.py`)
     - loading into Postgres (`postgres_loader.py`)
     - indexing into Elasticsearch (`es_indexer.py`)
     - source/entity import orchestration (`import_sources.py`, `import_entities.py`, `import_nested.py`)
   - This pipeline is the upstream data flow that populates the screening corpus used by the application.

8. **Async execution and background work**
   - `app/core/celery_app.py` and `app/workers/tasks.py` show Celery-based background processing.
   - This is likely used for long-running work such as bulk screening, report generation, imports/syncs, notifications, and data refresh jobs.
   - The repo also includes operational scripts like `sync_sanctions.py` and `seed_*` scripts, reinforcing that background/maintenance jobs are first-class.

9. **Tenant and security model**
   - `app/core/security.py` and `app/core/tenant.py` suggest authentication/authorization plus tenant scoping.
   - Given the presence of organizations, users, billing, and enterprise-specific migrations, the backend is designed to isolate data by organization/tenant.
   - `app/api/auth.py` and `app/api/users.py` are the main boundaries for identity flows, while the rest of the API likely depends on authenticated tenant context.

10. **Frontend application structure**
   - The frontend is a Next.js app in `frontend/app`, using the App Router.
   - It is split into:
     - public marketing/legal pages under `(public)`
     - authentication pages under `(auth)`
     - authenticated product UI under `(dashboard)`
   - Dashboard routes cover screening, bulk screening, cases, history, monitoring, activity, global search, settings, and detailed screening result views.

11. **Frontend-to-backend interaction**
   - The frontend contains API route handlers under `frontend/app/api/auth/*`, which likely proxy or mediate auth actions such as login, registration, and 2FA verification.
   - Most product screens are UI-only clients that consume backend APIs for screening, history, cases, dashboard stats, and user/account state.
   - Shared UI widgets live in `frontend/app/components/*`, especially dashboard charts and KPI cards, showing the frontend is largely a presentation layer over backend-driven data.

12. **Deployment and operational packaging**
   - Both backend and frontend have Dockerfiles, and the repo includes `docker-compose.yml` and `docker-compose-prod.yml`, so the system is intended to run as coordinated containerized services.
   - `ngrok.yml` and tunnel scripts indicate local/external exposure workflows for development or demo access.
   - The backend README references a localhost web interface, but the actual repo layout shows a modern split deployment: API/service backend plus a separate Next.js frontend.

13. **External/data dependencies to show in a diagram**
   - OpenSanctions is the key external data source feeding the screening corpus.
   - Elasticsearch is the main retrieval/indexing dependency.
   - PostgreSQL-like relational persistence is the main transactional store.
   - Celery provides asynchronous processing between API requests and long-running jobs.

14. **Diagram-level flow to capture**
   - Source data enters through ETL/import scripts → normalized entities are stored and indexed → backend APIs query DB/Elasticsearch for screening and analytics → async tasks handle bulk/long-running work → frontend dashboard consumes these APIs for analyst workflows and reporting.

Main entry points: [`backend/app/services`](https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/services) (Services), [`backend/app/main.py`](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/main.py) (App entry), [`frontend/app/(dashboard)`](https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(dashboard)) (Dashboard UI), [`backend/app/api/screenings.py`](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/screenings.py) (Screening API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>FastAPI entrypoint<br/>[main.py]"]
  node_backend_api_screening["Screening API<br/>domain routers<br/>[screenings.py]"]
  node_backend_api_cases["Case API<br/>domain routers<br/>[case_management.py]"]
  node_backend_api_analytics["Insights API<br/>domain routers<br/>[analytics.py]"]
  node_backend_api_identity["Identity API<br/>domain routers<br/>[auth.py]"]
  node_backend_api_compliance["Ops API<br/>domain routers<br/>[billing.py]"]
  node_backend_services["Services<br/>business logic"]
  node_backend_core["Core infra<br/>platform layer"]
  node_backend_db_models[("Data model<br/>storage layer<br/>[session.py]")]
  node_backend_schemas["Contracts"]
  node_backend_etl["ETL pipeline<br/>ingestion pipeline"]
  node_backend_workers["Workers<br/>async jobs<br/>[tasks.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_public["Public site<br/>Next.js public routes"]
  node_frontend_auth["Auth UI<br/>Next.js auth routes"]
  node_frontend_dashboard["Dashboard UI<br/>Next.js app routes"]
  node_frontend_api_routes["Auth routes<br/>route handlers<br/>[route.ts]"]
  node_frontend_components["Shared UI<br/>components"]
end

subgraph group_external["External systems"]
  node_external_postgres[("Postgres<br/>relational store")]
  node_external_elastic[("Elasticsearch<br/>search index")]
  node_external_celery["Celery<br/>job queue"]
  node_external_sources["OpenSanctions<br/>source data"]
end

node_backend_main -->|"mounts"| node_backend_api_screening
node_backend_main -->|"mounts"| node_backend_api_cases
node_backend_main -->|"mounts"| node_backend_api_analytics
node_backend_main -->|"mounts"| node_backend_api_identity
node_backend_main -->|"mounts"| node_backend_api_compliance
node_backend_api_screening -->|"uses"| node_backend_services
node_backend_api_cases -->|"uses"| node_backend_services
node_backend_api_analytics -->|"uses"| node_backend_services
node_backend_api_identity -->|"uses"| node_backend_core
node_backend_api_compliance -->|"uses"| node_backend_services
node_backend_services -->|"persists"| node_backend_db_models
node_backend_services -->|"uses"| node_backend_core
node_backend_etl -->|"ingests"| node_external_sources
node_backend_etl -->|"loads"| node_external_postgres
node_backend_etl -->|"indexes"| node_external_elastic
node_backend_workers -->|"runs on"| node_external_celery
node_backend_workers -->|"invokes"| node_backend_services
node_backend_core -->|"queries"| node_external_elastic
node_backend_core -->|"configures"| node_external_celery
node_backend_db_models -->|"stores in"| node_external_postgres
node_frontend_dashboard -->|"consumes"| node_backend_api_screening
node_frontend_dashboard -->|"consumes"| node_backend_api_cases
node_frontend_dashboard -->|"consumes"| node_backend_api_analytics
node_frontend_dashboard -->|"consumes"| node_backend_api_identity
node_frontend_auth -->|"calls"| node_frontend_api_routes
node_frontend_public -->|"shares"| node_frontend_components
node_frontend_dashboard -->|"uses"| node_frontend_components
node_frontend_api_routes -->|"proxies"| node_backend_api_identity
node_backend_api_screening -->|"validates"| node_backend_schemas
node_backend_api_cases -->|"validates"| node_backend_schemas
node_backend_api_analytics -->|"validates"| node_backend_schemas
node_backend_services -->|"shapes"| node_backend_schemas

click node_backend_main "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/main.py"
click node_backend_api_screening "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/screenings.py"
click node_backend_api_cases "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/case_management.py"
click node_backend_api_analytics "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/analytics.py"
click node_backend_api_identity "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/auth.py"
click node_backend_api_compliance "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/billing.py"
click node_backend_services "https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/services"
click node_backend_core "https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/core"
click node_backend_db_models "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/db/session.py"
click node_backend_schemas "https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/schemas"
click node_backend_etl "https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/etl"
click node_backend_workers "https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/workers/tasks.py"
click node_frontend_public "https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(public)"
click node_frontend_auth "https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(auth)"
click node_frontend_dashboard "https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(dashboard)"
click node_frontend_api_routes "https://github.com/md-arman-hossain-007/aoble/blob/master/frontend/app/api/auth/login/route.ts"
click node_frontend_components "https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/components"

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 node_backend_main,node_backend_api_screening,node_backend_api_cases,node_backend_api_analytics,node_backend_api_identity,node_backend_api_compliance,node_backend_services,node_backend_core,node_backend_db_models,node_backend_schemas,node_backend_etl,node_backend_workers toneBlue
class node_frontend_public,node_frontend_auth,node_frontend_dashboard,node_frontend_api_routes,node_frontend_components toneAmber
class node_external_postgres,node_external_elastic,node_external_celery,node_external_sources toneMint
```

## Components

### Backend

FastAPI service, domain APIs, business logic, persistence, and ETL pipeline.

- [App entry](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/main.py): FastAPI entrypoint · Bootstraps the backend application and mounts routers and core services. · `backend/app/main.py`
- [Screening API](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/screenings.py): domain routers · Primary screening and bulk screening endpoints for analyst workflows. · `backend/app/api/screenings.py`
- [Case API](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/case_management.py): domain routers · Case management and review workflow endpoints. · `backend/app/api/case_management.py`
- [Insights API](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/analytics.py): domain routers · Analytics, stats, and monitoring endpoints for dashboards and operations. · `backend/app/api/analytics.py`
- [Identity API](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/auth.py): domain routers · Authentication, users, and admin boundaries for tenant-scoped access. · `backend/app/api/auth.py`
- [Ops API](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/api/billing.py): domain routers · Billing, compliance, integrations, notifications, and external search endpoints. · `backend/app/api/billing.py`
- [Services](https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/services): business logic · Core screening, search, reporting, analytics, notification, and enrichment logic. · `backend/app/services`
- [Core infra](https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/core): platform layer · Configuration, security, tenant scoping, Elasticsearch, and Celery wiring. · `backend/app/core`
- [Data model](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/db/session.py): storage layer · Database session plus persistence models for users, organizations, cases, screenings, and related records. · `backend/app/db/session.py`
- [Contracts](https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/schemas): api contracts · Request and response schemas shared across API boundaries. · `backend/app/schemas`
- [ETL pipeline](https://github.com/md-arman-hossain-007/aoble/tree/master/backend/app/etl): ingestion pipeline · Imports, normalizes, loads, and indexes sanctions-style source data. · `backend/app/etl`
- [Workers](https://github.com/md-arman-hossain-007/aoble/blob/master/backend/app/workers/tasks.py): async jobs · Celery task definitions for background and long-running processing. · `backend/app/workers/tasks.py`

### Frontend

Next.js dashboard, auth, public pages, and shared UI.

- [Public site](https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(public)): Next.js public routes · Marketing, legal, pricing, and enterprise pages. · `frontend/app/(public)`
- [Auth UI](https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(auth)): Next.js auth routes · Sign in, sign up, password reset, and related authentication screens. · `frontend/app/(auth)`
- [Dashboard UI](https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/(dashboard)): Next.js app routes · Authenticated analyst workspace for screening, cases, history, monitoring, and settings. · `frontend/app/(dashboard)`
- [Auth routes](https://github.com/md-arman-hossain-007/aoble/blob/master/frontend/app/api/auth/login/route.ts): route handlers · Frontend API handlers that mediate login, registration, and 2FA flows. · `frontend/app/api/auth/login/route.ts`
- [Shared UI](https://github.com/md-arman-hossain-007/aoble/tree/master/frontend/app/components): components · Reusable dashboard widgets, controls, modals, and theme utilities. · `frontend/app/components`

### External systems

Datastores, search, async processing, and source data dependencies.

- **Postgres**: relational store · System of record for users, organizations, screenings, cases, audits, notifications, and analytics state.
- **Elasticsearch**: search index · Indexed retrieval layer for screening corpus and large-scale matching.
- **Celery**: job queue · Asynchronous execution layer for imports, bulk work, reports, and refresh jobs.
- **OpenSanctions**: source data · Upstream sanctions/watchlist data feeding the screening corpus.

## Connections

- App entry → Screening API: mounts · Registers screening-related routers into the application.
- App entry → Case API: mounts · Registers case management routers into the application.
- App entry → Insights API: mounts · Registers analytics and monitoring routers.
- App entry → Identity API: mounts · Registers auth, user, and admin routers.
- App entry → Ops API: mounts · Registers billing, compliance, integrations, and notification routers.
- Screening API → Services: uses · Delegates screening and search work to service layer.
- Case API → Services: uses · Delegates case workflow logic to services.
- Insights API → Services: uses · Delegates metrics and reporting logic to services.
- Identity API → Core infra: uses · Uses security and tenant context for authenticated access.
- Ops API → Services: uses · Delegates notifications, integrations, and external search behavior.
- Services → Data model: persists · Reads and writes the transactional data model.
- Services → Core infra: uses · Uses Elasticsearch, configuration, and tenant/security helpers.
- ETL pipeline → OpenSanctions: ingests · Downloads and normalizes upstream sanctions data.
- ETL pipeline → Postgres: loads · Stores normalized entities and source records in the relational database.
- ETL pipeline → Elasticsearch: indexes · Builds the search index used by screening.
- Workers → Celery: runs on · Executes asynchronous background tasks through Celery.
- Workers → Services: invokes · Reuses business logic for bulk jobs, reports, and refresh work.
- Core infra → Elasticsearch: queries · Provides the application search/index integration.
- Core infra → Celery: configures · Wires task execution and background processing.
- Data model → Postgres: stores in · Maps persistent entities to the relational database.
- Dashboard UI → Screening API: consumes · Uses backend screening endpoints for analyst workflows.
- Dashboard UI → Case API: consumes · Uses backend case management endpoints for review work.
- Dashboard UI → Insights API: consumes · Uses backend analytics and monitoring endpoints.
- Dashboard UI → Identity API: consumes · Uses authentication and user state from backend.
- Auth UI → Auth routes: calls · Uses local auth route handlers for login and registration flows.
- Public site → Shared UI: shares · Uses shared UI elements where needed.
- Dashboard UI → Shared UI: uses · Builds dashboard screens from reusable widgets and controls.
- Auth routes → Identity API: proxies · Mediates authentication actions to the backend.
- Screening API → Contracts: validates · Uses request and response contracts.
- Case API → Contracts: validates · Uses case management contracts.
- Insights API → Contracts: validates · Uses analytics and stats contracts.
- Services → Contracts: shapes · Relies on shared DTOs and response models.