# beone-capston/beone-mvp architecture

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

- Interactive diagram: https://gitdiagram.com/beone-capston/beone-mvp
- Repository: https://github.com/beone-capston/beone-mvp

## Overview

BeONE simulates choosing the held card with the greatest expected monthly benefit just before a simulated payment; it does not process real payments. The main workflow spans order creation, recommendation from card and monthly-state inputs, simulated approval, and ledger recording. Other major capabilities include member sessions, card management, CODEF connection/synchronization, and Android biometric activation. The excerpts show several service-level calls; unsampled controller wiring and frontend API calls are not inferred.

Main entry points: [`backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java`](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java) (Recommendation service), [`backend/src/main/java/com/beone/api/card/application/UserCardService.java`](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/card/application/UserCardService.java) (Held cards), [`backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java`](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java) (Simulated payment), [`backend/src/main/java/com/beone/api/codef/application/CodefSyncService.java`](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/codef/application/CodefSyncService.java) (CODEF sync)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client apps"]
  node_frontend["Web app<br/>[App.tsx]"]
  node_android["Android shell<br/>[MainActivity.kt]"]
  node_device_auth["Device authentication"]
end

subgraph group_identity["Identity and cards"]
  node_sessions["Member sessions"]
  node_card_service["Held cards"]
end

subgraph group_recommend["Recommendation"]
  node_monthly_state["Monthly state"]
  node_recommendation["Recommendation service"]
  node_engine["Benefit engine<br/>[HeldCardInput.java]"]
  node_rules["Benefit rules<br/>[RuleCatalog.java]"]
end

subgraph group_transactions["Transactions and data"]
  node_api["Backend API"]
  node_orders["Virtual orders<br/>[OrderService.java]"]
  node_ledger[("Transaction ledger")]
  node_payment["Simulated payment"]
end

subgraph group_integrations["External integration"]
  node_codef_sync["CODEF sync"]
  node_codef{{"CODEF service"}}
end

node_user(("User"))

node_user -.->|"uses"| node_frontend
node_user -.->|"uses"| node_android
node_android -.->|"authenticates"| node_device_auth
node_recommendation -->|"reads order"| node_orders
node_recommendation -->|"lists cards"| node_card_service
node_recommendation -->|"loads state"| node_monthly_state
node_recommendation -->|"reads activity"| node_ledger
node_ledger -->|"lists held cards"| node_card_service
node_payment -->|"recalculates"| node_recommendation
node_payment -->|"reads order"| node_orders
node_codef_sync -->|"registers cards"| node_card_service
node_codef_sync -.->|"fetches data"| node_codef

click node_frontend "https://github.com/beone-capston/beone-mvp/blob/develop/frontend/src/App.tsx"
click node_android "https://github.com/beone-capston/beone-mvp/blob/develop/android/app/src/main/java/com/beone/app/MainActivity.kt"
click node_device_auth "https://github.com/beone-capston/beone-mvp/blob/develop/android/app/src/main/java/com/beone/app/auth/DeviceAuthenticator.kt"
click node_api "https://github.com/beone-capston/beone-mvp/tree/develop/backend/src/main/java/com/beone/api"
click node_sessions "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/auth/application/AuthSessionService.java"
click node_card_service "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/card/application/UserCardService.java"
click node_orders "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/order/application/OrderService.java"
click node_monthly_state "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/monthlystate/application/MonthlyStateService.java"
click node_ledger "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/ledger/application/LedgerQueryService.java"
click node_recommendation "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java"
click node_engine "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/benefit/engine/HeldCardInput.java"
click node_rules "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/benefit/rule/RuleCatalog.java"
click node_payment "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java"
click node_codef_sync "https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/codef/application/CodefSyncService.java"

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_frontend,node_android,node_device_auth,node_user toneBlue
class node_sessions,node_card_service toneAmber
class node_monthly_state,node_recommendation,node_engine,node_rules toneMint
class node_api,node_orders,node_ledger,node_payment toneRose
class node_codef_sync,node_codef toneIndigo
```

## Components

### Client apps

- [Web app](https://github.com/beone-capston/beone-mvp/blob/develop/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Android shell](https://github.com/beone-capston/beone-mvp/blob/develop/android/app/src/main/java/com/beone/app/MainActivity.kt): `android/app/src/main/java/com/beone/app/MainActivity.kt`
- [Device authentication](https://github.com/beone-capston/beone-mvp/blob/develop/android/app/src/main/java/com/beone/app/auth/DeviceAuthenticator.kt): `android/app/src/main/java/com/beone/app/auth/DeviceAuthenticator.kt`

### Identity and cards

- [Member sessions](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/auth/application/AuthSessionService.java): `backend/src/main/java/com/beone/api/auth/application/AuthSessionService.java`
- [Held cards](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/card/application/UserCardService.java): `backend/src/main/java/com/beone/api/card/application/UserCardService.java`

### Recommendation

- [Monthly state](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/monthlystate/application/MonthlyStateService.java): `backend/src/main/java/com/beone/api/monthlystate/application/MonthlyStateService.java`
- [Recommendation service](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java): `backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java`
- [Benefit engine](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/benefit/engine/HeldCardInput.java): `backend/src/main/java/com/beone/api/benefit/engine/HeldCardInput.java`
- [Benefit rules](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/benefit/rule/RuleCatalog.java): `backend/src/main/java/com/beone/api/benefit/rule/RuleCatalog.java`

### Transactions and data

- [Backend API](https://github.com/beone-capston/beone-mvp/tree/develop/backend/src/main/java/com/beone/api): `backend/src/main/java/com/beone/api`
- [Virtual orders](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/order/application/OrderService.java): `backend/src/main/java/com/beone/api/order/application/OrderService.java`
- [Transaction ledger](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/ledger/application/LedgerQueryService.java): `backend/src/main/java/com/beone/api/ledger/application/LedgerQueryService.java`
- [Simulated payment](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java): `backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java`

### External integration

- [CODEF sync](https://github.com/beone-capston/beone-mvp/blob/develop/backend/src/main/java/com/beone/api/codef/application/CodefSyncService.java): `backend/src/main/java/com/beone/api/codef/application/CodefSyncService.java`
- **CODEF service**

### Other components

- **User**

## Connections

- User → Web app: uses (evidence: `README.md`)
- User → Android shell: uses (evidence: `README.md`)
- Android shell → Device authentication: authenticates
- Recommendation service → Virtual orders: reads order (evidence: `backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java`)
- Recommendation service → Held cards: lists cards (evidence: `backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java`)
- Recommendation service → Monthly state: loads state (evidence: `backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java`)
- Recommendation service → Transaction ledger: reads activity (evidence: `backend/src/main/java/com/beone/api/recommendation/application/RecommendationService.java`)
- Transaction ledger → Held cards: lists held cards (evidence: `backend/src/main/java/com/beone/api/ledger/application/LedgerQueryService.java`)
- Simulated payment → Recommendation service: recalculates (evidence: `backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java`)
- Simulated payment → Virtual orders: reads order (evidence: `backend/src/main/java/com/beone/api/payment/application/SimulatedPaymentService.java`)
- CODEF sync → Held cards: registers cards (evidence: `backend/src/main/java/com/beone/api/codef/application/CodefSyncService.java`)
- CODEF sync → CODEF service: fetches data
