# islambek996/marking-ais architecture

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

- Interactive diagram: https://gitdiagram.com/islambek996/marking-ais
- Repository: https://github.com/islambek996/marking-ais

## Overview

Marking AIS is an in-memory MVP for managing textbook marking codes, with a separate public DataMatrix checker. The main workflow is participant and textbook management, code ordering with billing reservation/capture, code generation, and status transitions; the scanner decodes a code and looks it up in AIS. The README also documents operations, aggregation, documents, history, users/roles, and dashboard capabilities; several are represented at their enclosing source directory because their implementation was not sampled.

Main entry points: [`backend/src/main/java/kg/teksher/ais/code/MarkingCodeService.java`](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeService.java) (Marking code service), [`backend/src/main/resources/static/app.js`](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/resources/static/app.js) (AIS web UI), [`backend/src/main/java/kg/teksher/ais/order/CodeOrderService.java`](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/order/CodeOrderService.java) (Code order service), [`frontend/src/main.jsx`](https://github.com/islambek996/marking-ais/blob/main/frontend/src/main.jsx) (Dashboard UI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["User interfaces"]
  node_ais_ui["AIS web UI<br/>[app.js]"]
  node_dashboard_ui["Dashboard UI<br/>[main.jsx]"]
  node_scanner_ui["DataMatrix scanner<br/>[App.jsx]"]
  node_gs1_parser["GS1 parser<br/>[gs1.js]"]
  node_ais_api_client["AIS API client<br/>[api.js]"]
end

subgraph group_catalog["Participants and catalog"]
  node_participant_api["Participant API"]
  node_participant_service["Participant service"]
  node_participant_repo["Participant repository"]
  node_textbook_api["Textbook API"]
  node_textbook_service["Textbook service"]
  node_textbook_repo["Textbook repository"]
  node_product_groups["Product groups"]
end

subgraph group_marking["Codes and operations"]
  node_code_api["Marking code API"]
  node_code_service["Marking code service"]
  node_code_repo["Marking code repository"]
  node_serial_generator["Serial generator"]
  node_gs1_builder["GS1 payload builder<br/>[Gs1Builder.java]"]
  node_datamatrix["DataMatrix generator"]
  node_marking_operations["Code operations, aggregation, documents, history"]
end

subgraph group_finance["Orders and billing"]
  node_code_orders["Code order service"]
  node_billing_api["Billing API"]
  node_billing_service["Billing service"]
  node_billing_memory["In-memory billing"]
end

subgraph group_platform["AIS platform"]
  node_ais_app["AIS application"]
  node_ais_error_handler["API error handler"]
  node_ais_memory_repos[("In-memory repositories")]
end

node_ais_user(("AIS user"))
node_public_checker(("Public checker"))
node_zxing["DataMatrix decoder"]

node_ais_user -->|"uses"| node_ais_ui
node_ais_ui -->|"requests"| node_participant_api
node_ais_ui -->|"requests"| node_textbook_api
node_ais_ui -->|"requests"| node_code_api
node_ais_ui -->|"orders"| node_code_orders
node_ais_ui -->|"requests"| node_billing_api
node_ais_user -->|"views"| node_dashboard_ui
node_dashboard_ui -->|"loads"| node_participant_api
node_dashboard_ui -->|"loads"| node_textbook_api
node_dashboard_ui -->|"loads"| node_code_api
node_dashboard_ui -->|"loads"| node_code_orders
node_public_checker -->|"scans"| node_scanner_ui
node_scanner_ui -->|"decodes"| node_zxing
node_scanner_ui -->|"parses"| node_gs1_parser
node_scanner_ui -->|"looks up"| node_ais_api_client
node_ais_api_client -->|"queries"| node_code_api
node_participant_api -->|"dispatches"| node_participant_service
node_participant_service -->|"reads/writes"| node_participant_repo
node_textbook_api -->|"dispatches"| node_textbook_service
node_textbook_service -->|"reads/writes"| node_textbook_repo
node_code_api -->|"dispatches"| node_code_service
node_code_service -->|"reads/writes"| node_code_repo
node_code_service -->|"generates serials"| node_serial_generator
node_code_service -->|"builds payload"| node_gs1_builder
node_code_service -->|"renders code"| node_datamatrix
node_code_service -->|"uses textbook"| node_textbook_service
node_code_orders -->|"loads textbook"| node_textbook_service
node_code_orders -->|"calculates/reserves"| node_billing_service
node_code_orders -->|"generates codes"| node_code_service
node_code_orders -->|"captures/releases"| node_billing_service
node_billing_api -->|"dispatches"| node_billing_service
node_billing_memory -->|"stores state"| node_ais_memory_repos
node_marking_operations -->|"transitions codes"| node_code_service
node_ais_app -->|"handles API errors"| node_ais_error_handler

click node_ais_ui "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/resources/static/app.js"
click node_dashboard_ui "https://github.com/islambek996/marking-ais/blob/main/frontend/src/main.jsx"
click node_scanner_ui "https://github.com/islambek996/marking-ais/blob/main/scanner/src/App.jsx"
click node_gs1_parser "https://github.com/islambek996/marking-ais/blob/main/scanner/src/gs1.js"
click node_ais_api_client "https://github.com/islambek996/marking-ais/blob/main/scanner/src/api.js"
click node_ais_app "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/AisApplication.java"
click node_participant_api "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/participant/ParticipantController.java"
click node_participant_service "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/participant/ParticipantService.java"
click node_participant_repo "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/participant/ParticipantRepository.java"
click node_textbook_api "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/textbook/TextbookController.java"
click node_textbook_service "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/textbook/TextbookService.java"
click node_textbook_repo "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/textbook/TextbookRepository.java"
click node_product_groups "https://github.com/islambek996/marking-ais/tree/main/backend/src/main/java/kg/teksher/ais/product"
click node_code_api "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeController.java"
click node_code_service "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeService.java"
click node_code_repo "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeRepository.java"
click node_serial_generator "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/SerialGenerator.java"
click node_gs1_builder "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/Gs1Builder.java"
click node_datamatrix "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/DataMatrixService.java"
click node_marking_operations "https://github.com/islambek996/marking-ais/tree/main/backend/src/main/java/kg/teksher/ais"
click node_code_orders "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/order/CodeOrderService.java"
click node_billing_api "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/billing/BillingController.java"
click node_billing_service "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/billing/BillingService.java"
click node_billing_memory "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/billing/InMemoryBillingService.java"
click node_ais_error_handler "https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/common/GlobalExceptionHandler.java"
click node_ais_memory_repos "https://github.com/islambek996/marking-ais/tree/main/backend/src/main/java/kg/teksher/ais"

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_ais_ui,node_dashboard_ui,node_scanner_ui,node_gs1_parser,node_ais_api_client,node_ais_user toneBlue
class node_participant_api,node_participant_service,node_participant_repo,node_textbook_api,node_textbook_service,node_textbook_repo,node_product_groups toneAmber
class node_code_api,node_code_service,node_code_repo,node_serial_generator,node_gs1_builder,node_datamatrix,node_marking_operations toneMint
class node_code_orders,node_billing_api,node_billing_service,node_billing_memory toneRose
class node_ais_app,node_ais_error_handler,node_ais_memory_repos,node_public_checker,node_zxing toneIndigo
```

## Components

### User interfaces

- [AIS web UI](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/resources/static/app.js): `backend/src/main/resources/static/app.js`
- [Dashboard UI](https://github.com/islambek996/marking-ais/blob/main/frontend/src/main.jsx): `frontend/src/main.jsx`
- [DataMatrix scanner](https://github.com/islambek996/marking-ais/blob/main/scanner/src/App.jsx): `scanner/src/App.jsx`
- [GS1 parser](https://github.com/islambek996/marking-ais/blob/main/scanner/src/gs1.js): `scanner/src/gs1.js`
- [AIS API client](https://github.com/islambek996/marking-ais/blob/main/scanner/src/api.js): `scanner/src/api.js`

### Participants and catalog

- [Participant API](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/participant/ParticipantController.java): `backend/src/main/java/kg/teksher/ais/participant/ParticipantController.java`
- [Participant service](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/participant/ParticipantService.java): `backend/src/main/java/kg/teksher/ais/participant/ParticipantService.java`
- [Participant repository](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/participant/ParticipantRepository.java): `backend/src/main/java/kg/teksher/ais/participant/ParticipantRepository.java`
- [Textbook API](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/textbook/TextbookController.java): `backend/src/main/java/kg/teksher/ais/textbook/TextbookController.java`
- [Textbook service](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/textbook/TextbookService.java): `backend/src/main/java/kg/teksher/ais/textbook/TextbookService.java`
- [Textbook repository](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/textbook/TextbookRepository.java): `backend/src/main/java/kg/teksher/ais/textbook/TextbookRepository.java`
- [Product groups](https://github.com/islambek996/marking-ais/tree/main/backend/src/main/java/kg/teksher/ais/product): `backend/src/main/java/kg/teksher/ais/product`

### Codes and operations

- [Marking code API](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeController.java): `backend/src/main/java/kg/teksher/ais/code/MarkingCodeController.java`
- [Marking code service](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeService.java): `backend/src/main/java/kg/teksher/ais/code/MarkingCodeService.java`
- [Marking code repository](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/MarkingCodeRepository.java): `backend/src/main/java/kg/teksher/ais/code/MarkingCodeRepository.java`
- [Serial generator](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/SerialGenerator.java): `backend/src/main/java/kg/teksher/ais/code/SerialGenerator.java`
- [GS1 payload builder](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/Gs1Builder.java): `backend/src/main/java/kg/teksher/ais/code/Gs1Builder.java`
- [DataMatrix generator](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/code/DataMatrixService.java): `backend/src/main/java/kg/teksher/ais/code/DataMatrixService.java`
- [Code operations, aggregation, documents, history](https://github.com/islambek996/marking-ais/tree/main/backend/src/main/java/kg/teksher/ais): `backend/src/main/java/kg/teksher/ais`

### Orders and billing

- [Code order service](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/order/CodeOrderService.java): `backend/src/main/java/kg/teksher/ais/order/CodeOrderService.java`
- [Billing API](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/billing/BillingController.java): `backend/src/main/java/kg/teksher/ais/billing/BillingController.java`
- [Billing service](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/billing/BillingService.java): `backend/src/main/java/kg/teksher/ais/billing/BillingService.java`
- [In-memory billing](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/billing/InMemoryBillingService.java): `backend/src/main/java/kg/teksher/ais/billing/InMemoryBillingService.java`

### AIS platform

- [AIS application](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/AisApplication.java): `backend/src/main/java/kg/teksher/ais/AisApplication.java`
- [API error handler](https://github.com/islambek996/marking-ais/blob/main/backend/src/main/java/kg/teksher/ais/common/GlobalExceptionHandler.java): `backend/src/main/java/kg/teksher/ais/common/GlobalExceptionHandler.java`
- [In-memory repositories](https://github.com/islambek996/marking-ais/tree/main/backend/src/main/java/kg/teksher/ais): `backend/src/main/java/kg/teksher/ais`

### Other components

- **AIS user**
- **Public checker**
- **DataMatrix decoder**

## Connections

- AIS user → AIS web UI: uses
- AIS web UI → Participant API: requests
- AIS web UI → Textbook API: requests
- AIS web UI → Marking code API: requests
- AIS web UI → Code order service: orders
- AIS web UI → Billing API: requests
- AIS user → Dashboard UI: views
- Dashboard UI → Participant API: loads
- Dashboard UI → Textbook API: loads
- Dashboard UI → Marking code API: loads
- Dashboard UI → Code order service: loads
- Public checker → DataMatrix scanner: scans
- DataMatrix scanner → DataMatrix decoder: decodes
- DataMatrix scanner → GS1 parser: parses
- DataMatrix scanner → AIS API client: looks up
- AIS API client → Marking code API: queries
- Participant API → Participant service: dispatches
- Participant service → Participant repository: reads/writes
- Textbook API → Textbook service: dispatches
- Textbook service → Textbook repository: reads/writes
- Marking code API → Marking code service: dispatches
- Marking code service → Marking code repository: reads/writes
- Marking code service → Serial generator: generates serials
- Marking code service → GS1 payload builder: builds payload
- Marking code service → DataMatrix generator: renders code
- Marking code service → Textbook service: uses textbook
- Code order service → Textbook service: loads textbook
- Code order service → Billing service: calculates/reserves
- Code order service → Marking code service: generates codes
- Code order service → Billing service: captures/releases
- Billing API → Billing service: dispatches
- In-memory billing → In-memory repositories: stores state
- Code operations, aggregation, documents, history → Marking code service: transitions codes
- AIS application → API error handler: handles API errors