How md-arman-hossain-007/aoble works
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: services Services · main.py App entry · (dashboard) Dashboard UI · screenings.py Screening API
Components 21
Backend
FastAPI service, domain APIs, business logic, persistence, and ETL pipeline.
- App entry · Bootstraps the backend application and mounts routers and core services.
backend/app/main.py - Screening API · Primary screening and bulk screening endpoints for analyst workflows.
backend/app/api/screenings.py - Case API · Case management and review workflow endpoints.
backend/app/api/case_management.py - Insights API · Analytics, stats, and monitoring endpoints for dashboards and operations.
backend/app/api/analytics.py - Identity API · Authentication, users, and admin boundaries for tenant-scoped access.
backend/app/api/auth.py - Ops API · Billing, compliance, integrations, notifications, and external search endpoints.
backend/app/api/billing.py - Services · Core screening, search, reporting, analytics, notification, and enrichment logic.
backend/app/services - Core infra · Configuration, security, tenant scoping, Elasticsearch, and Celery wiring.
backend/app/core - Data model · Database session plus persistence models for users, organizations, cases, screenings, and related records.
backend/app/db/session.py - Contracts · Request and response schemas shared across API boundaries.
backend/app/schemas - ETL pipeline · Imports, normalizes, loads, and indexes sanctions-style source data.
backend/app/etl - Workers · 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 · Marketing, legal, pricing, and enterprise pages.
frontend/app/(public) - Auth UI · Sign in, sign up, password reset, and related authentication screens.
frontend/app/(auth) - Dashboard UI · Authenticated analyst workspace for screening, cases, history, monitoring, and settings.
frontend/app/(dashboard) - Auth routes · Frontend API handlers that mediate login, registration, and 2FA flows.
frontend/app/api/auth/login/route.ts - Shared UI · Reusable dashboard widgets, controls, modals, and theme utilities.
frontend/app/components
External systems
Datastores, search, async processing, and source data dependencies.
- Postgres · System of record for users, organizations, screenings, cases, audits, notifications, and analytics state.
- Elasticsearch · Indexed retrieval layer for screening corpus and large-scale matching.
- Celery · Asynchronous execution layer for imports, bulk work, reports, and refresh jobs.
- OpenSanctions · Upstream sanctions/watchlist data feeding the screening corpus.
Connections 32
- 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.