# openbin-ai/platform architecture

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

- Interactive diagram: https://gitdiagram.com/openbin-ai/platform
- Repository: https://github.com/openbin-ai/platform

## Overview

#### Purpose and entry points
OpenAPK/OpenBin is a self-hostable collaborative security-research platform: OpenAPK analyzes Android APKs; OpenBin analyzes native binaries and scripts. Users access React SPAs, authenticate through OIDC, upload or attach analysis artifacts, inspect decompiled code, use BYOK LLM features, and create/share reports. Runtime entry points are `core/src/main/java/ai/openapk/core/CoreApplication.java`, `openapk-frontend/src/main.tsx`, `openbin-frontend/src/main.tsx`, and CLI `cli/main.go`.

#### API core and security boundary
`core/` is the central Java Spring Boot service and REST API. Controllers expose domain operations; services coordinate persistence, storage, workers, and LLMs. OAuth2 resource-server security validates bearer JWTs from Keycloak; current-user provisioning and authorization gates isolate private projects, while explicit public-read routes expose shared artifacts.
Paths: `core/src/main/java/ai/openapk/core/config/SecurityConfig.java`, `core/src/main/java/ai/openapk/core/auth/CurrentUserService.java`, `core/src/main/java/ai/openapk/core/projects/ProjectAccessGuard.java`.

#### Project ingestion, storage, and decompilation
Projects are the primary aggregate for uploaded APKs, binaries, and related derived artifacts. Ingestion is staged as initiate/finalize requests, then delegates decompilation or analysis. A storage abstraction keeps application services independent of local filesystem versus S3-backed source-of-truth; S3 uses a local cache and signed media URLs.
Paths: `core/src/main/java/ai/openapk/core/projects/ingest/IngestService.java`, `core/src/main/java/ai/openapk/core/projects/storage/ProjectStorage.java`, `core/src/main/java/ai/openapk/core/projects/JadxDecompileService.java`.

#### Isolated analysis workers
The core invokes separate containerized workers for expensive or tool-specific analysis. JADX produces Android decompilation; Ghidra handles native ELF/PE/Mach-O workflows and ingestion; Lambda-oriented workers analyze scripts, PyPI packages, and shell artifacts. Worker execution is asynchronous/quotable and materializes outputs back into project storage and database metadata.
Paths: `jadx-worker/app/main.py`, `ghidra-worker/app/main.py`, `core/src/main/java/ai/openapk/core/nativeanalysis/NativeAnalysisRunner.java`, `script-worker/src/handler.js`.

#### Research views and derived indexes
Backend modules turn stored analysis outputs into navigable research data: symbols/usages, call chains, manifests, JNI bridges, network and crypto indicators, database schemas, deobfuscation/renames, highlights, and search. These are project-scoped read/write APIs over analysis files plus relational metadata, rather than independent data pipelines.
Paths: `core/src/main/java/ai/openapk/core/symbols/SymbolService.java`, `core/src/main/java/ai/openapk/core/callchain/CallChainService.java`, `core/src/main/java/ai/openapk/core/analysis/StaticDigestService.java`.

#### AI, credentials, and governance
Users store encrypted provider credentials for Anthropic, OpenAI, or Bedrock. LLM calls build prompts from project artifacts, support streaming, audit usage, and enforce user/worker limits. AI also drives Q&A, deobfuscation, rename suggestions, call-chain narration, crypto reconstruction, and script findings.
Paths: `core/src/main/java/ai/openapk/core/credentials/LlmCredentialEncryptionService.java`, `core/src/main/java/ai/openapk/core/analysis/LlmInvoker.java`, `core/src/main/java/ai/openapk/core/usage/LlmUsageService.java`.

#### Collaboration and presentation clients
Two Vite/React clients specialize the common API for APK and binary workflows, reusing auth/API/components under `shared/`; a third Vite app is the OpenBin landing site. Projects support collaborators, presence, annotations/highlights, reports/templates, community publication, follows, votes, comments, notifications, and public views. The Go CLI automates authentication, uploads, decompilation, and native attachment.
Paths: `openapk-frontend/src/pages/ProjectView.tsx`, `openbin-frontend/src/pages/ProjectViewRoute.tsx`, `shared/components/CommentsThread.tsx`, `cli/cmd_root.go`.

#### Infrastructure and persistence
Postgres stores users, projects, credentials, reports, social data, job/usage records, and indexes, evolved through Flyway migrations. Docker Compose supplies Postgres, Keycloak with imported realm/theme, and optional MinIO for S3-compatible testing. Production storage integrates AWS S3/CloudFront; LLM providers and worker/Lambda invocations are external service boundaries.
Paths: `core/compose.yaml`, `core/src/main/resources/db/migration/V1__init.sql`, `core/src/main/java/ai/openapk/core/projects/analysis/CloudFrontUrlSigner.java`.

Main entry points: [`core/src/main/java/ai/openapk/core/CoreApplication.java`](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/CoreApplication.java) (Core REST API), [`core/src/main/java/ai/openapk/core/projects/storage/ProjectStorage.java`](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/storage/ProjectStorage.java) (Project Storage), [`core/src/main/java/ai/openapk/core/projects/ingest/IngestService.java`](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/ingest/IngestService.java) (Project Ingestion), [`core/src/main/java/ai/openapk/core/symbols/SymbolService.java`](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/symbols/SymbolService.java) (Research Views & Indexes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_apk_spa["OpenAPK React SPA<br/>Vite client<br/>[main.tsx]"]
  node_bin_spa["OpenBin React SPA<br/>Vite client<br/>[main.tsx]"]
  node_cli["Go CLI<br/>automation client<br/>[main.go]"]
end

subgraph group_core["Spring Boot Core"]
  node_core_api{{"Core REST API<br/>Spring Boot service"}}
  node_security["JWT Security<br/>resource-server boundary"]
  node_project_access["Project Access<br/>authorization service"]
  node_ingestion["Project Ingestion<br/>staged upload service<br/>[IngestService.java]"]
  node_project_storage["Project Storage<br/>storage abstraction"]
  node_native_runner["Native Analysis Runner<br/>worker orchestrator"]
  node_research_services["Research Views &amp; Indexes<br/>project-scoped services<br/>[SymbolService.java]"]
  node_ai_services["AI Analysis<br/>LLM orchestration<br/>[LlmInvoker.java]"]
  node_credential_usage["Credentials &amp; Usage<br/>governance services"]
  node_collaboration["Reports &amp; Collaboration<br/>domain API"]
end

subgraph group_workers["Isolated Workers"]
  node_jadx_worker{{"JADX Worker<br/>container worker<br/>[main.py]"}}
  node_ghidra_worker{{"Ghidra Worker<br/>container worker<br/>[main.py]"}}
  node_script_worker{{"Script Worker<br/>Lambda worker<br/>[handler.js]"}}
end

subgraph group_platform["Identity, Data &amp; External Services"]
  node_keycloak{{"Keycloak<br/>OIDC provider<br/>[compose.yaml]"}}
  node_postgres[("Postgres<br/>relational database<br/>[V1__init.sql]")]
  node_object_storage[("Object Storage<br/>S3 / local storage")]
  node_llm_providers{{"LLM Providers<br/>external AI APIs"}}
end

node_apk_spa -->|"REST API"| node_core_api
node_bin_spa -->|"REST API"| node_core_api
node_cli -->|"automates API"| node_core_api
node_core_api -->|"secures requests"| node_security
node_security -->|"validates JWTs"| node_keycloak
node_core_api -->|"authorizes project routes"| node_project_access
node_core_api -->|"uploads and attachments"| node_ingestion
node_ingestion -->|"stores artifacts"| node_project_storage
node_ingestion -.->|"APK jobs"| node_jadx_worker
node_ingestion -.->|"native jobs"| node_native_runner
node_ingestion -.->|"script jobs"| node_script_worker
node_native_runner -.->|"dispatches"| node_ghidra_worker
node_jadx_worker -->|"materializes outputs"| node_project_storage
node_ghidra_worker -->|"materializes outputs"| node_project_storage
node_script_worker -->|"materializes outputs"| node_project_storage
node_project_storage -->|"local or S3 backend"| node_object_storage
node_core_api -->|"research APIs"| node_research_services
node_research_services -->|"reads analysis files"| node_project_storage
node_core_api -->|"AI features"| node_ai_services
node_ai_services -->|"credentials and limits"| node_credential_usage
node_ai_services -->|"provider calls"| node_llm_providers
node_core_api -->|"reports and sharing"| node_collaboration
node_core_api -->|"domain persistence"| node_postgres
node_research_services -->|"derived metadata"| node_postgres
node_credential_usage -->|"encrypted credentials and usage"| node_postgres

click node_apk_spa "https://github.com/openbin-ai/platform/blob/master/openapk-frontend/src/main.tsx"
click node_bin_spa "https://github.com/openbin-ai/platform/blob/master/openbin-frontend/src/main.tsx"
click node_cli "https://github.com/openbin-ai/platform/blob/master/cli/main.go"
click node_core_api "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/CoreApplication.java"
click node_security "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/config/SecurityConfig.java"
click node_project_access "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/ProjectAccessGuard.java"
click node_ingestion "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/ingest/IngestService.java"
click node_project_storage "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/storage/ProjectStorage.java"
click node_native_runner "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/nativeanalysis/NativeAnalysisRunner.java"
click node_research_services "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/symbols/SymbolService.java"
click node_ai_services "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/analysis/LlmInvoker.java"
click node_credential_usage "https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/credentials/LlmCredentialEncryptionService.java"
click node_jadx_worker "https://github.com/openbin-ai/platform/blob/master/jadx-worker/app/main.py"
click node_ghidra_worker "https://github.com/openbin-ai/platform/blob/master/ghidra-worker/app/main.py"
click node_script_worker "https://github.com/openbin-ai/platform/blob/master/script-worker/src/handler.js"
click node_keycloak "https://github.com/openbin-ai/platform/blob/master/core/compose.yaml"
click node_postgres "https://github.com/openbin-ai/platform/blob/master/core/src/main/resources/db/migration/V1__init.sql"

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_apk_spa,node_bin_spa,node_cli toneBlue
class node_core_api,node_security,node_project_access,node_ingestion,node_project_storage,node_native_runner,node_research_services,node_ai_services,node_credential_usage,node_collaboration toneAmber
class node_jadx_worker,node_ghidra_worker,node_script_worker toneMint
class node_keycloak,node_postgres,node_object_storage,node_llm_providers toneRose
```

## Components

### Clients

- [OpenAPK React SPA](https://github.com/openbin-ai/platform/blob/master/openapk-frontend/src/main.tsx): Vite client · APK research workspace. · `openapk-frontend/src/main.tsx`
- [OpenBin React SPA](https://github.com/openbin-ai/platform/blob/master/openbin-frontend/src/main.tsx): Vite client · Native-binary research workspace. · `openbin-frontend/src/main.tsx`
- [Go CLI](https://github.com/openbin-ai/platform/blob/master/cli/main.go): automation client · Authenticates, uploads, and starts analysis. · `cli/main.go`

### Spring Boot Core

- [Core REST API](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/CoreApplication.java): Spring Boot service · Central domain API and orchestration runtime. · `core/src/main/java/ai/openapk/core/CoreApplication.java`
- [JWT Security](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/config/SecurityConfig.java): resource-server boundary · Validates OIDC bearer tokens and protects routes. · `core/src/main/java/ai/openapk/core/config/SecurityConfig.java`
- [Project Access](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/ProjectAccessGuard.java): authorization service · Provisions current users and enforces project isolation. · `core/src/main/java/ai/openapk/core/projects/ProjectAccessGuard.java`
- [Project Ingestion](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/ingest/IngestService.java): staged upload service · Initiates/finalizes artifacts and dispatches analysis. · `core/src/main/java/ai/openapk/core/projects/ingest/IngestService.java`
- [Project Storage](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/projects/storage/ProjectStorage.java): storage abstraction · Abstracts local or S3-backed artifacts and derived outputs. · `core/src/main/java/ai/openapk/core/projects/storage/ProjectStorage.java`
- [Native Analysis Runner](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/nativeanalysis/NativeAnalysisRunner.java): worker orchestrator · Dispatches native analysis asynchronously. · `core/src/main/java/ai/openapk/core/nativeanalysis/NativeAnalysisRunner.java`
- [Research Views & Indexes](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/symbols/SymbolService.java): project-scoped services · Serves symbols, call chains, indicators, search, and derived metadata. · `core/src/main/java/ai/openapk/core/symbols/SymbolService.java`
- [AI Analysis](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/analysis/LlmInvoker.java): LLM orchestration · Builds artifact-grounded prompts and streams research features. · `core/src/main/java/ai/openapk/core/analysis/LlmInvoker.java`
- [Credentials & Usage](https://github.com/openbin-ai/platform/blob/master/core/src/main/java/ai/openapk/core/credentials/LlmCredentialEncryptionService.java): governance services · Encrypts BYOK credentials and enforces/audits LLM limits. · `core/src/main/java/ai/openapk/core/credentials/LlmCredentialEncryptionService.java`
- **Reports & Collaboration**: domain API · Provides annotations, reports, publication, and social activity.

### Isolated Workers

- [JADX Worker](https://github.com/openbin-ai/platform/blob/master/jadx-worker/app/main.py): container worker · Decompiles Android APKs. · `jadx-worker/app/main.py`
- [Ghidra Worker](https://github.com/openbin-ai/platform/blob/master/ghidra-worker/app/main.py): container worker · Analyzes ELF, PE, and Mach-O artifacts. · `ghidra-worker/app/main.py`
- [Script Worker](https://github.com/openbin-ai/platform/blob/master/script-worker/src/handler.js): Lambda worker · Analyzes scripts, packages, and shell artifacts. · `script-worker/src/handler.js`

### Identity, Data & External Services

- [Keycloak](https://github.com/openbin-ai/platform/blob/master/core/compose.yaml): OIDC provider · Issues JWTs for platform users. · `core/compose.yaml`
- [Postgres](https://github.com/openbin-ai/platform/blob/master/core/src/main/resources/db/migration/V1__init.sql): relational database · Stores project, user, report, social, job, usage, and index metadata. · `core/src/main/resources/db/migration/V1__init.sql`
- **Object Storage**: S3 / local storage · Source of truth for uploaded artifacts and worker outputs.
- **LLM Providers**: external AI APIs · Anthropic, OpenAI, and Bedrock provider boundary.

## Connections

- OpenAPK React SPA → Core REST API: REST API
- OpenBin React SPA → Core REST API: REST API
- Go CLI → Core REST API: automates API
- Core REST API → JWT Security: secures requests
- JWT Security → Keycloak: validates JWTs
- Core REST API → Project Access: authorizes project routes
- Core REST API → Project Ingestion: uploads and attachments
- Project Ingestion → Project Storage: stores artifacts
- Project Ingestion → JADX Worker: APK jobs
- Project Ingestion → Native Analysis Runner: native jobs
- Project Ingestion → Script Worker: script jobs
- Native Analysis Runner → Ghidra Worker: dispatches
- JADX Worker → Project Storage: materializes outputs
- Ghidra Worker → Project Storage: materializes outputs
- Script Worker → Project Storage: materializes outputs
- Project Storage → Object Storage: local or S3 backend
- Core REST API → Research Views & Indexes: research APIs
- Research Views & Indexes → Project Storage: reads analysis files
- Core REST API → AI Analysis: AI features
- AI Analysis → Credentials & Usage: credentials and limits
- AI Analysis → LLM Providers: provider calls
- Core REST API → Reports & Collaboration: reports and sharing
- Core REST API → Postgres: domain persistence
- Research Views & Indexes → Postgres: derived metadata
- Credentials & Usage → Postgres: encrypted credentials and usage