# laithanhmai334/b2b-carton-selling-website-backend architecture

> Architecture diagram of the GitHub repository laithanhmai334/b2b-carton-selling-website-backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laithanhmai334/b2b-carton-selling-website-backend
- Repository: https://github.com/laithanhmai334/b2b-carton-selling-website-backend

## Overview

#### Purpose and Runtime
This is a Maven-based Java/Spring Boot backend for a B2B carton-selling and contracting workflow. It exposes REST APIs for company onboarding and verification, user access, document/certificate handling, contract negotiation and signing, order forms, pricing, and payments. The runtime starts at `src/main/java/com/nhanguyen/b2bcarton/B2bcartonApplication.java`; environment configuration is under `src/main/resources/application.yaml` and `src/main/resources/application.properties`.

#### HTTP API and Application Boundary
Controllers are the inbound REST boundary, translating request DTOs into service calls and response DTOs. Major API domains include companies and verification, contracts, invitations, users/permissions, and AI:
- `src/main/java/com/nhanguyen/b2bcarton/controller/CompanyController.java`
- `src/main/java/com/nhanguyen/b2bcarton/controller/ContractController.java`
- `src/main/java/com/nhanguyen/b2bcarton/controller/AIController.java`

DTO packages separate API payloads from persistence entities, with `ApiResponse` providing a common response envelope.

#### Identity, JWT, and Authorization
Authentication/token lifecycle is handled by authentication services and token entities; invalidated tokens are persisted for revocation. Spring Security is configured with a custom JWT decoder and authentication entry point. Fine-grained authorization is an AOP permission check via annotation/aspect, beyond endpoint authentication.
- `src/main/java/com/nhanguyen/b2bcarton/configuration/SecurityConfig.java`
- `src/main/java/com/nhanguyen/b2bcarton/service/AuthService.java`
- `src/main/java/com/nhanguyen/b2bcarton/security/aspect/PermissionAspect.java`

Control flow: request → security/JWT validation → controller → permission aspect where annotated → domain service.

#### Company Onboarding, Trust, and Documents
Company registration establishes company/user-related records, then verification combines tax-code validation, email-domain checks, uploaded documents, and certificates. Company, certificate, and document entities persist status-driven workflows; services isolate validation, storage, and verification decisions.
- `src/main/java/com/nhanguyen/b2bcarton/service/RegisterCompanyService.java`
- `src/main/java/com/nhanguyen/b2bcarton/service/CompanyVerificationService.java`
- `src/main/java/com/nhanguyen/b2bcarton/entity/CompanyDocument.java`

Document processing additionally crosses external-service boundaries through storage, OCR, and certificate management.

#### Commercial Contract Lifecycle
The core transaction model spans contract requests, negotiation messages, contracts and terms, MSAs, and order forms. Policy, pricing, PDF generation, and digital signatures are explicit domain services, indicating a staged flow from request/negotiation to agreement generation, signing, and order execution.
- `src/main/java/com/nhanguyen/b2bcarton/service/ContractRequestService.java`
- `src/main/java/com/nhanguyen/b2bcarton/service/ContractService.java`
- `src/main/java/com/nhanguyen/b2bcarton/service/DigitalSignatureService.java`

Key persisted state is represented by `ContractRequest`, `NegotiationMessage`, `Contract`, `MSA`, and `OrderForm` entities.

#### Persistence and Domain State
Spring Data-style repository interfaces are the persistence boundary for the relational domain model. Entities encode lifecycle states through enums such as company, document, certificate, contract-request, contract, MSA, and order-form statuses.
- `src/main/java/com/nhanguyen/b2bcarton/repository/CompanyRepository.java`
- `src/main/java/com/nhanguyen/b2bcarton/repository/ContractRepository.java`
- `src/main/java/com/nhanguyen/b2bcarton/entity/Invoice.java`

Services generally own repository interaction; mappers mediate entity-to-response transformations.

#### External Integrations and Background Work
Infrastructure-facing services include Cloudinary-backed file storage configuration, HTTP calls through `RestTemplate`, mail delivery, payment/VietQR generation, OCR, AI, tax-code verification, encryption, and PDF/signature operations.
- `src/main/java/com/nhanguyen/b2bcarton/configuration/CloudinaryConfig.java`
- `src/main/java/com/nhanguyen/b2bcarton/configuration/RestTemplateConfig.java`
- `src/main/java/com/nhanguyen/b2bcarton/service/PaymentService.java`

A scheduled tier recalculation process updates customer-tier-related state independently of request handling:
`src/main/java/com/nhanguyen/b2bcarton/scheduler/TierRecalculationJob.java`.

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API &amp; Security"]
  node_app{{"Spring Boot runtime"}}
  node_controllers["REST controllers<br/>HTTP API"]
  node_dto["DTOs &amp; API envelope<br/>API models"]
  node_security["JWT security<br/>Spring Security"]
  node_permissions["Permission aspect<br/>AOP authorization"]
  node_auth["Authentication service<br/>identity service<br/>[AuthService.java]"]
end

subgraph group_onboarding["Onboarding &amp; Trust"]
  node_registration["Company registration<br/>onboarding service"]
  node_verification["Company verification<br/>trust service"]
  node_documents["Company documents<br/>domain entity"]
end

subgraph group_commerce["Contract Commerce"]
  node_contract_request["Contract requests &amp; negotiation<br/>commerce service"]
  node_contracts["Contract lifecycle<br/>commerce service"]
  node_signature["Digital signatures<br/>signing service"]
end

subgraph group_platform["Persistence &amp; Integrations"]
  node_payment["Payments &amp; VietQR<br/>payment service"]
  node_repositories[("Spring Data repositories<br/>persistence boundary")]
  node_domain[("Relational domain state<br/>entities<br/>[Invoice.java]")]
  node_external{{"External service adapters<br/>integration services"}}
  node_cloudinary{{"Cloudinary storage<br/>file storage integration"}}
  node_tier_job(("Tier recalculation job<br/>scheduled job"))
end

node_app -->|"boots"| node_security
node_security -->|"validates JWT before"| node_controllers
node_controllers -->|"maps payloads"| node_dto
node_controllers -->|"invokes annotated checks"| node_permissions
node_permissions -->|"uses identity context"| node_auth
node_controllers -->|"onboarding APIs"| node_registration
node_controllers -->|"verification APIs"| node_verification
node_registration -->|"persists records"| node_repositories
node_verification -->|"evaluates"| node_documents
node_verification -->|"stores uploads"| node_cloudinary
node_verification -->|"uses OCR and tax checks"| node_external
node_controllers -->|"request APIs"| node_contract_request
node_contract_request -->|"negotiation to agreement"| node_contracts
node_contracts -->|"sends agreements"| node_signature
node_contracts -->|"drives order payment"| node_payment
node_contract_request -->|"persists workflow"| node_repositories
node_contracts -->|"persists lifecycle"| node_repositories
node_repositories -->|"reads and writes"| node_domain
node_auth -->|"stores revoked tokens"| node_repositories
node_tier_job -->|"updates tier state"| node_repositories

click node_app "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/B2bcartonApplication.java"
click node_controllers "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/controller/CompanyController.java"
click node_security "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/configuration/SecurityConfig.java"
click node_permissions "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/security/aspect/PermissionAspect.java"
click node_auth "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/AuthService.java"
click node_registration "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/RegisterCompanyService.java"
click node_verification "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/CompanyVerificationService.java"
click node_documents "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/entity/CompanyDocument.java"
click node_contract_request "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/ContractRequestService.java"
click node_contracts "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/ContractService.java"
click node_signature "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/DigitalSignatureService.java"
click node_payment "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/PaymentService.java"
click node_repositories "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/repository/CompanyRepository.java"
click node_domain "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/entity/Invoice.java"
click node_external "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/configuration/RestTemplateConfig.java"
click node_cloudinary "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/configuration/CloudinaryConfig.java"
click node_tier_job "https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/scheduler/TierRecalculationJob.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_app,node_controllers,node_dto,node_security,node_permissions,node_auth toneBlue
class node_registration,node_verification,node_documents toneAmber
class node_contract_request,node_contracts,node_signature toneMint
class node_payment,node_repositories,node_domain,node_external,node_cloudinary,node_tier_job toneRose
```

## Components

### API & Security

- [Spring Boot runtime](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/B2bcartonApplication.java): application · Application entry point and runtime bootstrap. · `src/main/java/com/nhanguyen/b2bcarton/B2bcartonApplication.java`
- [REST controllers](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/controller/CompanyController.java): HTTP API · Company, contract, and AI request boundary. · `src/main/java/com/nhanguyen/b2bcarton/controller/CompanyController.java`
- **DTOs & API envelope**: API models · Separates request and response payloads from entities.
- [JWT security](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/configuration/SecurityConfig.java): Spring Security · Authenticates requests with custom JWT handling. · `src/main/java/com/nhanguyen/b2bcarton/configuration/SecurityConfig.java`
- [Permission aspect](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/security/aspect/PermissionAspect.java): AOP authorization · Applies fine-grained annotated permission checks. · `src/main/java/com/nhanguyen/b2bcarton/security/aspect/PermissionAspect.java`
- [Authentication service](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/AuthService.java): identity service · Manages token lifecycle and revocation. · `src/main/java/com/nhanguyen/b2bcarton/service/AuthService.java`

### Onboarding & Trust

- [Company registration](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/RegisterCompanyService.java): onboarding service · Establishes company and related user records. · `src/main/java/com/nhanguyen/b2bcarton/service/RegisterCompanyService.java`
- [Company verification](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/CompanyVerificationService.java): trust service · Combines tax, email-domain, document, and certificate checks. · `src/main/java/com/nhanguyen/b2bcarton/service/CompanyVerificationService.java`
- [Company documents](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/entity/CompanyDocument.java): domain entity · Status-driven uploaded-document state. · `src/main/java/com/nhanguyen/b2bcarton/entity/CompanyDocument.java`

### Contract Commerce

- [Contract requests & negotiation](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/ContractRequestService.java): commerce service · Starts requests and negotiation-message workflow. · `src/main/java/com/nhanguyen/b2bcarton/service/ContractRequestService.java`
- [Contract lifecycle](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/ContractService.java): commerce service · Manages contracts, terms, MSAs, and order forms. · `src/main/java/com/nhanguyen/b2bcarton/service/ContractService.java`
- [Digital signatures](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/DigitalSignatureService.java): signing service · Signs generated commercial agreements. · `src/main/java/com/nhanguyen/b2bcarton/service/DigitalSignatureService.java`

### Persistence & Integrations

- [Payments & VietQR](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/service/PaymentService.java): payment service · Generates payment flows for commercial transactions. · `src/main/java/com/nhanguyen/b2bcarton/service/PaymentService.java`
- [Spring Data repositories](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/repository/CompanyRepository.java): persistence boundary · Repository interfaces used by domain services. · `src/main/java/com/nhanguyen/b2bcarton/repository/CompanyRepository.java`
- [Relational domain state](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/entity/Invoice.java): entities · Lifecycle entities include contracts, MSAs, order forms, and invoices. · `src/main/java/com/nhanguyen/b2bcarton/entity/Invoice.java`
- [External service adapters](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/configuration/RestTemplateConfig.java): integration services · Storage, OCR, AI, tax verification, mail, PDF, and encryption. · `src/main/java/com/nhanguyen/b2bcarton/configuration/RestTemplateConfig.java`
- [Cloudinary storage](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/configuration/CloudinaryConfig.java): file storage integration · Stores uploaded company documents. · `src/main/java/com/nhanguyen/b2bcarton/configuration/CloudinaryConfig.java`
- [Tier recalculation job](https://github.com/laithanhmai334/b2b-carton-selling-website-backend/blob/main/src/main/java/com/nhanguyen/b2bcarton/scheduler/TierRecalculationJob.java): scheduled job · Updates customer-tier state outside request handling. · `src/main/java/com/nhanguyen/b2bcarton/scheduler/TierRecalculationJob.java`

## Connections

- Spring Boot runtime → JWT security: boots
- JWT security → REST controllers: validates JWT before
- REST controllers → DTOs & API envelope: maps payloads
- REST controllers → Permission aspect: invokes annotated checks
- Permission aspect → Authentication service: uses identity context
- REST controllers → Company registration: onboarding APIs
- REST controllers → Company verification: verification APIs
- Company registration → Spring Data repositories: persists records
- Company verification → Company documents: evaluates
- Company verification → Cloudinary storage: stores uploads
- Company verification → External service adapters: uses OCR and tax checks
- REST controllers → Contract requests & negotiation: request APIs
- Contract requests & negotiation → Contract lifecycle: negotiation to agreement
- Contract lifecycle → Digital signatures: sends agreements
- Contract lifecycle → Payments & VietQR: drives order payment
- Contract requests & negotiation → Spring Data repositories: persists workflow
- Contract lifecycle → Spring Data repositories: persists lifecycle
- Spring Data repositories → Relational domain state: reads and writes
- Authentication service → Spring Data repositories: stores revoked tokens
- Tier recalculation job → Spring Data repositories: updates tier state
