# royaldev06/bitsentry architecture

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

- Interactive diagram: https://gitdiagram.com/royaldev06/bitsentry
- Repository: https://github.com/royaldev06/bitsentry

## Overview

BitSentry AML is a Bitcoin AML monitoring and investigation application. Analysts enter through a React dashboard and can navigate to alerts, transactions, address investigation, and cases; the documented workflow spans monitoring and risk assessment through alert review and case resolution. The sampled dashboard uses React Query and mock-backed service functions, while the backend directories are largely package initializers. Backend domain capabilities and blockchain integration are therefore represented at directory level without asserting unsampled call paths.

Main entry points: [`frontend/src/App.tsx`](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/App.tsx) (Application routes), [`frontend/src/hooks/useDashboard.ts`](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/hooks/useDashboard.ts) (Dashboard queries), [`frontend/src/pages/Dashboard/DashboardPage.tsx`](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Dashboard/DashboardPage.tsx) (Dashboard page), [`frontend/src/components/dashboard/RiskDistributionCard.tsx`](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/RiskDistributionCard.tsx) (Risk distribution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Analyst interface"]
  node_app["Application routes<br/>[App.tsx]"]
  node_layout["Application layout<br/>[AppLayout.tsx]"]
  node_dashboardpage["Dashboard page<br/>[DashboardPage.tsx]"]
  node_summary["Summary cards<br/>[SummaryCards.tsx]"]
  node_alertcard["Alert summary"]
  node_riskcard["Risk distribution"]
  node_activitycard["Recent activity"]
  node_dashboardui["Dashboard presentation<br/>[SectionCard.tsx]"]
  node_stateview["Loading and empty states<br/>[StateView.tsx]"]
  node_riskbadge["Risk badge<br/>[RiskBadge.tsx]"]
  node_dashutils["Dashboard formatting<br/>[dashboardUtils.ts]"]
  node_dashboardhook["Dashboard queries<br/>[useDashboard.ts]"]
  node_theme["Theme preference<br/>[useTheme.ts]"]
  node_alertsui["Alerts screen<br/>[Alerts.tsx]"]
  node_transactionsui["Transactions screen<br/>[Transactions.tsx]"]
  node_addressesui["Address investigation screen<br/>[Addresses.tsx]"]
  node_casesui["Cases screen<br/>[Cases.tsx]"]
end

subgraph group_backend["AML backend domains"]
  node_monitoring["Transaction monitoring"]
  node_risk["Risk assessment"]
  node_detection["Detection and rules"]
  node_alerts["Alert management"]
  node_addressdomain["Address investigation"]
  node_casedomain["Case management"]
  node_bitcoin["Bitcoin data services"]
  node_dashboarddomain["Backend dashboard"]
end

subgraph group_data["Data and contracts"]
  node_dashboardservice["Dashboard data service<br/>[dashboard.ts]"]
  node_dashcontracts["Dashboard data contracts<br/>[dashboard.ts]"]
  node_db[("Application database<br/>[database.py]")]
end

node_analyst(("Compliance analyst"))
node_blockchain{{"Bitcoin blockchain data"}}

node_analyst -->|"uses"| node_app
node_app -->|"routes to"| node_dashboardpage
node_app -->|"routes to"| node_alertsui
node_app -->|"routes to"| node_transactionsui
node_app -->|"routes to"| node_addressesui
node_app -->|"routes to"| node_casesui
node_app -->|"renders"| node_layout
node_dashboardpage -->|"renders"| node_summary
node_dashboardpage -->|"renders"| node_alertcard
node_dashboardpage -->|"renders"| node_riskcard
node_dashboardpage -->|"renders"| node_activitycard
node_dashboardpage -->|"uses"| node_theme
node_summary -->|"queries"| node_dashboardhook
node_alertcard -->|"queries"| node_dashboardhook
node_riskcard -->|"queries"| node_dashboardhook
node_activitycard -->|"queries"| node_dashboardhook
node_dashboardhook -->|"calls"| node_dashboardservice
node_dashboardservice -->|"uses"| node_dashcontracts
node_riskcard -->|"renders"| node_dashboardui
node_activitycard -->|"renders"| node_dashboardui
node_alertcard -->|"renders"| node_dashboardui
node_riskcard -->|"renders"| node_stateview
node_activitycard -->|"renders"| node_stateview
node_activitycard -->|"renders"| node_riskbadge
node_riskbadge -->|"uses labels"| node_dashutils
node_riskcard -->|"uses labels"| node_dashutils
node_dashboardhook -.->|"retrieves monitoring data"| node_monitoring
node_dashboardhook -.->|"retrieves risk data"| node_risk
node_detection -.->|"generates alerts"| node_alerts
node_alerts -.->|"initiates investigations"| node_casedomain
node_addressesui -.->|"investigates"| node_addressdomain
node_transactionsui -.->|"reviews transactions"| node_monitoring
node_bitcoin -.->|"integrates data"| node_blockchain
node_monitoring -.->|"persists data"| node_db
node_alerts -.->|"stores alerts"| node_db
node_casedomain -.->|"stores cases"| node_db

click node_app "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/App.tsx"
click node_layout "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/layout/AppLayout.tsx"
click node_dashboardpage "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Dashboard/DashboardPage.tsx"
click node_summary "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/SummaryCards.tsx"
click node_alertcard "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/AlertSummaryCard.tsx"
click node_riskcard "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/RiskDistributionCard.tsx"
click node_activitycard "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/RecentActivityCard.tsx"
click node_dashboardui "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/SectionCard.tsx"
click node_stateview "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/StateView.tsx"
click node_riskbadge "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/ui/RiskBadge.tsx"
click node_dashutils "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/dashboardUtils.ts"
click node_dashboardhook "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/hooks/useDashboard.ts"
click node_dashboardservice "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/services/dashboard.ts"
click node_dashcontracts "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/types/dashboard.ts"
click node_theme "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/hooks/useTheme.ts"
click node_alertsui "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Alerts/Alerts.tsx"
click node_transactionsui "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Transactions/Transactions.tsx"
click node_addressesui "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Addresses/Addresses.tsx"
click node_casesui "https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Cases/Cases.tsx"
click node_monitoring "https://github.com/royaldev06/bitsentry/tree/main/backend/app/transactions"
click node_risk "https://github.com/royaldev06/bitsentry/tree/main/backend/app/risk"
click node_detection "https://github.com/royaldev06/bitsentry/tree/main/backend/app/detection"
click node_alerts "https://github.com/royaldev06/bitsentry/tree/main/backend/app/alerts"
click node_addressdomain "https://github.com/royaldev06/bitsentry/tree/main/backend/app/addresses"
click node_casedomain "https://github.com/royaldev06/bitsentry/tree/main/backend/app/cases"
click node_bitcoin "https://github.com/royaldev06/bitsentry/tree/main/backend/app/bitcoin"
click node_dashboarddomain "https://github.com/royaldev06/bitsentry/tree/main/backend/app/dashboard"
click node_db "https://github.com/royaldev06/bitsentry/blob/main/backend/app/database.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 node_app,node_layout,node_dashboardpage,node_summary,node_alertcard,node_riskcard,node_activitycard,node_dashboardui,node_stateview,node_riskbadge,node_dashutils,node_dashboardhook,node_theme,node_alertsui,node_transactionsui,node_addressesui,node_casesui toneBlue
class node_monitoring,node_risk,node_detection,node_alerts,node_addressdomain,node_casedomain,node_bitcoin,node_dashboarddomain toneAmber
class node_dashboardservice,node_dashcontracts,node_db toneMint
class node_analyst,node_blockchain toneIndigo
```

## Components

### Analyst interface

- [Application routes](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Application layout](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/layout/AppLayout.tsx): `frontend/src/components/layout/AppLayout.tsx`
- [Dashboard page](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Dashboard/DashboardPage.tsx): `frontend/src/pages/Dashboard/DashboardPage.tsx`
- [Summary cards](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/SummaryCards.tsx): `frontend/src/components/dashboard/SummaryCards.tsx`
- [Alert summary](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/AlertSummaryCard.tsx): `frontend/src/components/dashboard/AlertSummaryCard.tsx`
- [Risk distribution](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/RiskDistributionCard.tsx): `frontend/src/components/dashboard/RiskDistributionCard.tsx`
- [Recent activity](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/RecentActivityCard.tsx): `frontend/src/components/dashboard/RecentActivityCard.tsx`
- [Dashboard presentation](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/SectionCard.tsx): `frontend/src/components/dashboard/SectionCard.tsx`
- [Loading and empty states](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/StateView.tsx): `frontend/src/components/dashboard/StateView.tsx`
- [Risk badge](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/ui/RiskBadge.tsx): `frontend/src/components/ui/RiskBadge.tsx`
- [Dashboard formatting](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/components/dashboard/dashboardUtils.ts): `frontend/src/components/dashboard/dashboardUtils.ts`
- [Dashboard queries](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/hooks/useDashboard.ts): `frontend/src/hooks/useDashboard.ts`
- [Theme preference](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/hooks/useTheme.ts): `frontend/src/hooks/useTheme.ts`
- [Alerts screen](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Alerts/Alerts.tsx): `frontend/src/pages/Alerts/Alerts.tsx`
- [Transactions screen](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Transactions/Transactions.tsx): `frontend/src/pages/Transactions/Transactions.tsx`
- [Address investigation screen](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Addresses/Addresses.tsx): `frontend/src/pages/Addresses/Addresses.tsx`
- [Cases screen](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/pages/Cases/Cases.tsx): `frontend/src/pages/Cases/Cases.tsx`

### AML backend domains

- [Transaction monitoring](https://github.com/royaldev06/bitsentry/tree/main/backend/app/transactions): `backend/app/transactions`
- [Risk assessment](https://github.com/royaldev06/bitsentry/tree/main/backend/app/risk): `backend/app/risk`
- [Detection and rules](https://github.com/royaldev06/bitsentry/tree/main/backend/app/detection): `backend/app/detection`
- [Alert management](https://github.com/royaldev06/bitsentry/tree/main/backend/app/alerts): `backend/app/alerts`
- [Address investigation](https://github.com/royaldev06/bitsentry/tree/main/backend/app/addresses): `backend/app/addresses`
- [Case management](https://github.com/royaldev06/bitsentry/tree/main/backend/app/cases): `backend/app/cases`
- [Bitcoin data services](https://github.com/royaldev06/bitsentry/tree/main/backend/app/bitcoin): `backend/app/bitcoin`
- [Backend dashboard](https://github.com/royaldev06/bitsentry/tree/main/backend/app/dashboard): `backend/app/dashboard`

### Data and contracts

- [Dashboard data service](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/services/dashboard.ts): `frontend/src/services/dashboard.ts`
- [Dashboard data contracts](https://github.com/royaldev06/bitsentry/blob/main/frontend/src/types/dashboard.ts): `frontend/src/types/dashboard.ts`
- [Application database](https://github.com/royaldev06/bitsentry/blob/main/backend/app/database.py): `backend/app/database.py`

### Other components

- **Compliance analyst**
- **Bitcoin blockchain data**

## Connections

- Compliance analyst → Application routes: uses (evidence: `README.md`)
- Application routes → Dashboard page: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Alerts screen: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Transactions screen: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Address investigation screen: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Cases screen: routes to (evidence: `frontend/src/App.tsx`)
- Application routes → Application layout: renders (evidence: `frontend/src/App.tsx`)
- Dashboard page → Summary cards: renders (evidence: `frontend/src/pages/Dashboard/DashboardPage.tsx`)
- Dashboard page → Alert summary: renders (evidence: `frontend/src/pages/Dashboard/DashboardPage.tsx`)
- Dashboard page → Risk distribution: renders (evidence: `frontend/src/pages/Dashboard/DashboardPage.tsx`)
- Dashboard page → Recent activity: renders (evidence: `frontend/src/pages/Dashboard/DashboardPage.tsx`)
- Dashboard page → Theme preference: uses (evidence: `frontend/src/pages/Dashboard/DashboardPage.tsx`)
- Summary cards → Dashboard queries: queries (evidence: `frontend/src/components/dashboard/SummaryCards.tsx`)
- Alert summary → Dashboard queries: queries (evidence: `frontend/src/components/dashboard/AlertSummaryCard.tsx`)
- Risk distribution → Dashboard queries: queries (evidence: `frontend/src/components/dashboard/RiskDistributionCard.tsx`)
- Recent activity → Dashboard queries: queries (evidence: `frontend/src/components/dashboard/RecentActivityCard.tsx`)
- Dashboard queries → Dashboard data service: calls (evidence: `frontend/src/hooks/useDashboard.ts`)
- Dashboard data service → Dashboard data contracts: uses (evidence: `frontend/src/services/dashboard.ts`)
- Risk distribution → Dashboard presentation: renders (evidence: `frontend/src/components/dashboard/RiskDistributionCard.tsx`)
- Recent activity → Dashboard presentation: renders (evidence: `frontend/src/components/dashboard/RecentActivityCard.tsx`)
- Alert summary → Dashboard presentation: renders (evidence: `frontend/src/components/dashboard/AlertSummaryCard.tsx`)
- Risk distribution → Loading and empty states: renders (evidence: `frontend/src/components/dashboard/RiskDistributionCard.tsx`)
- Recent activity → Loading and empty states: renders (evidence: `frontend/src/components/dashboard/RecentActivityCard.tsx`)
- Recent activity → Risk badge: renders (evidence: `frontend/src/components/dashboard/RecentActivityCard.tsx`)
- Risk badge → Dashboard formatting: uses labels (evidence: `frontend/src/components/ui/RiskBadge.tsx`)
- Risk distribution → Dashboard formatting: uses labels (evidence: `frontend/src/components/dashboard/RiskDistributionCard.tsx`)
- Dashboard queries → Transaction monitoring: retrieves monitoring data (evidence: `README.md`)
- Dashboard queries → Risk assessment: retrieves risk data (evidence: `README.md`)
- Detection and rules → Alert management: generates alerts (evidence: `README.md`)
- Alert management → Case management: initiates investigations (evidence: `README.md`)
- Address investigation screen → Address investigation: investigates (evidence: `README.md`)
- Transactions screen → Transaction monitoring: reviews transactions (evidence: `README.md`)
- Bitcoin data services → Bitcoin blockchain data: integrates data (evidence: `README.md`)
- Transaction monitoring → Application database: persists data
- Alert management → Application database: stores alerts
- Case management → Application database: stores cases
