# thevladbog/markiro architecture

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

- Interactive diagram: https://gitdiagram.com/thevladbog/markiro
- Repository: https://github.com/thevladbog/markiro

## Overview

Markiro is an offline-first Chestny ZNAK production platform. Its main workflow spans office configuration, line-side scanning and aggregation, local journaling with eventual synchronization, server-side traceability and inventory, and external regulatory exchange. The graph also preserves the documented kiosk, signer, labeling, billing, and SaaS capabilities. Relationships between product surfaces and infrastructure come from the README; source excerpts provide only limited internal implementation evidence, so unsampled internal links are omitted.

Main entry points: [`apps/api/src/app.module.ts`](https://github.com/thevladbog/markiro/blob/main/apps/api/src/app.module.ts) (NestJS API), [`apps/admin/src/app.tsx`](https://github.com/thevladbog/markiro/blob/main/apps/admin/src/app.tsx) (Admin cabinet), [`apps/station/src/App.tsx`](https://github.com/thevladbog/markiro/blob/main/apps/station/src/App.tsx) (Line station), [`apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/sync/SyncEngine.kt`](https://github.com/thevladbog/markiro/blob/main/apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/sync/SyncEngine.kt) (Handheld workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surfaces["Product surfaces"]
  node_admin["Admin cabinet<br/>[app.tsx]"]
  node_station["Line station<br/>[App.tsx]"]
  node_kiosk["Pickup kiosk<br/>[App.tsx]"]
  node_signer["Signer agent<br/>[App.tsx]"]
  node_handheld["Handheld workflows<br/>[SyncEngine.kt]"]
end

subgraph group_production["Production workflows"]
  node_catalog["Product catalog"]
  node_shifts["Shifts and scanning"]
  node_aggregation["Boxes and SSCC"]
  node_inventory["Inventory workflows"]
  node_labels["Label templates"]
  node_pickup["Employee pickup"]
end

subgraph group_platform["Platform services"]
  node_api["NestJS API<br/>[app.module.ts]"]
  node_auth["Authentication<br/>[auth.module.ts]"]
  node_code_status["Code-status ingest"]
  node_national_catalog["National catalog import"]
end

subgraph group_commercial["SaaS and billing"]
  node_billing["Billing and offers"]
  node_billing_profiles["Billing profiles"]
  node_saas_admin["SaaS operator panel<br/>[app.tsx]"]
end

subgraph group_state["State and integrations"]
  node_database[("PostgreSQL<br/>[client.ts]")]
  node_local_journal[("Station local journal<br/>[mirror.ts]")]
  node_handheld_db[("Handheld local database")]
end

node_operator(("Factory operators"))
node_true_api{{"Chestny ZNAK True API"}}
node_commerce{{"CommerceML / 1C"}}

node_operator -->|"configures"| node_admin
node_operator -->|"scans production"| node_station
node_operator -->|"collects orders"| node_kiosk
node_admin -->|"uses"| node_api
node_kiosk -->|"uses"| node_api
node_station -.->|"syncs when connected"| node_api
node_station -->|"journals locally"| node_local_journal
node_handheld -.->|"synchronizes"| node_api
node_handheld -.->|"stores offline work"| node_handheld_db
node_signer -->|"provides True API token"| node_api
node_api -->|"reads and writes"| node_database
node_api -.->|"integrates"| node_true_api
node_api -.->|"exchanges data"| node_commerce
node_admin -->|"manages products"| node_catalog
node_admin -->|"manages shifts"| node_shifts
node_admin -->|"manages boxes"| node_aggregation
node_admin -->|"manages inventory"| node_inventory
node_admin -->|"edits templates"| node_labels
node_admin -->|"audits pickup"| node_pickup
node_api -.->|"enforces identity"| node_auth
node_api -->|"ingests status data"| node_code_status
node_api -->|"supports imports"| node_national_catalog
node_api -->|"serves billing"| node_billing
node_billing -->|"uses seller policy"| node_billing_profiles
node_saas_admin -.->|"uses"| node_api

click node_admin "https://github.com/thevladbog/markiro/blob/main/apps/admin/src/app.tsx"
click node_station "https://github.com/thevladbog/markiro/blob/main/apps/station/src/App.tsx"
click node_kiosk "https://github.com/thevladbog/markiro/blob/main/apps/kiosk/src/App.tsx"
click node_signer "https://github.com/thevladbog/markiro/blob/main/apps/signer/src/App.tsx"
click node_handheld "https://github.com/thevladbog/markiro/blob/main/apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/sync/SyncEngine.kt"
click node_catalog "https://github.com/thevladbog/markiro/tree/main/apps/admin/src/pages/catalog"
click node_shifts "https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/shifts"
click node_aggregation "https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/boxes"
click node_inventory "https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/inventories"
click node_labels "https://github.com/thevladbog/markiro/tree/main/apps/admin/src/pages/labels"
click node_pickup "https://github.com/thevladbog/markiro/tree/main/apps/admin/src/pages/pickup"
click node_api "https://github.com/thevladbog/markiro/blob/main/apps/api/src/app.module.ts"
click node_auth "https://github.com/thevladbog/markiro/blob/main/apps/api/src/auth/auth.module.ts"
click node_code_status "https://github.com/thevladbog/markiro/blob/main/apps/api/src/modules/chz-code-statuses/chz-code-status-ingest.service.ts"
click node_national_catalog "https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/national-catalog"
click node_database "https://github.com/thevladbog/markiro/blob/main/packages/db/src/client.ts"
click node_local_journal "https://github.com/thevladbog/markiro/blob/main/apps/station/src/lib/mirror.ts"
click node_handheld_db "https://github.com/thevladbog/markiro/blob/main/apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/storage/HandheldDatabase.kt"
click node_billing "https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/billing"
click node_billing_profiles "https://github.com/thevladbog/markiro/blob/main/apps/api/src/modules/billing-profiles/billing-profiles.service.ts"
click node_saas_admin "https://github.com/thevladbog/markiro/blob/main/apps/saas-admin/src/app.tsx"

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_admin,node_station,node_kiosk,node_signer,node_handheld toneBlue
class node_catalog,node_shifts,node_aggregation,node_inventory,node_labels,node_pickup toneAmber
class node_api,node_auth,node_code_status,node_national_catalog,node_true_api toneMint
class node_billing,node_billing_profiles,node_saas_admin toneRose
class node_database,node_local_journal,node_handheld_db,node_operator,node_commerce toneIndigo
```

## Components

### Product surfaces

- [Admin cabinet](https://github.com/thevladbog/markiro/blob/main/apps/admin/src/app.tsx): `apps/admin/src/app.tsx`
- [Line station](https://github.com/thevladbog/markiro/blob/main/apps/station/src/App.tsx): `apps/station/src/App.tsx`
- [Pickup kiosk](https://github.com/thevladbog/markiro/blob/main/apps/kiosk/src/App.tsx): `apps/kiosk/src/App.tsx`
- [Signer agent](https://github.com/thevladbog/markiro/blob/main/apps/signer/src/App.tsx): `apps/signer/src/App.tsx`
- [Handheld workflows](https://github.com/thevladbog/markiro/blob/main/apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/sync/SyncEngine.kt): `apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/sync/SyncEngine.kt`

### Production workflows

- [Product catalog](https://github.com/thevladbog/markiro/tree/main/apps/admin/src/pages/catalog): `apps/admin/src/pages/catalog`
- [Shifts and scanning](https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/shifts): `apps/api/src/modules/shifts`
- [Boxes and SSCC](https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/boxes): `apps/api/src/modules/boxes`
- [Inventory workflows](https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/inventories): `apps/api/src/modules/inventories`
- [Label templates](https://github.com/thevladbog/markiro/tree/main/apps/admin/src/pages/labels): `apps/admin/src/pages/labels`
- [Employee pickup](https://github.com/thevladbog/markiro/tree/main/apps/admin/src/pages/pickup): `apps/admin/src/pages/pickup`

### Platform services

- [NestJS API](https://github.com/thevladbog/markiro/blob/main/apps/api/src/app.module.ts): `apps/api/src/app.module.ts`
- [Authentication](https://github.com/thevladbog/markiro/blob/main/apps/api/src/auth/auth.module.ts): `apps/api/src/auth/auth.module.ts`
- [Code-status ingest](https://github.com/thevladbog/markiro/blob/main/apps/api/src/modules/chz-code-statuses/chz-code-status-ingest.service.ts): `apps/api/src/modules/chz-code-statuses/chz-code-status-ingest.service.ts`
- [National catalog import](https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/national-catalog): `apps/api/src/modules/national-catalog`

### SaaS and billing

- [Billing and offers](https://github.com/thevladbog/markiro/tree/main/apps/api/src/modules/billing): `apps/api/src/modules/billing`
- [Billing profiles](https://github.com/thevladbog/markiro/blob/main/apps/api/src/modules/billing-profiles/billing-profiles.service.ts): `apps/api/src/modules/billing-profiles/billing-profiles.service.ts`
- [SaaS operator panel](https://github.com/thevladbog/markiro/blob/main/apps/saas-admin/src/app.tsx): `apps/saas-admin/src/app.tsx`

### State and integrations

- [PostgreSQL](https://github.com/thevladbog/markiro/blob/main/packages/db/src/client.ts): `packages/db/src/client.ts`
- [Station local journal](https://github.com/thevladbog/markiro/blob/main/apps/station/src/lib/mirror.ts): `apps/station/src/lib/mirror.ts`
- [Handheld local database](https://github.com/thevladbog/markiro/blob/main/apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/storage/HandheldDatabase.kt): `apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/storage/HandheldDatabase.kt`

### Other components

- **Factory operators**
- **Chestny ZNAK True API**
- **CommerceML / 1C**

## Connections

- Factory operators → Admin cabinet: configures (evidence: `README.md`)
- Factory operators → Line station: scans production (evidence: `README.md`)
- Factory operators → Pickup kiosk: collects orders (evidence: `README.md`)
- Admin cabinet → NestJS API: uses (evidence: `README.md`)
- Pickup kiosk → NestJS API: uses (evidence: `README.md`)
- Line station → NestJS API: syncs when connected (evidence: `README.md`)
- Line station → Station local journal: journals locally (evidence: `README.md`)
- Handheld workflows → NestJS API: synchronizes
- Handheld workflows → Handheld local database: stores offline work (evidence: `apps/handheld/app/src/main/kotlin/app/markiro/handheld/core/sync/SyncEngine.kt`)
- Signer agent → NestJS API: provides True API token (evidence: `README.md`)
- NestJS API → PostgreSQL: reads and writes (evidence: `README.md`)
- NestJS API → Chestny ZNAK True API: integrates (evidence: `README.md`)
- NestJS API → CommerceML / 1C: exchanges data (evidence: `README.md`)
- Admin cabinet → Product catalog: manages products (evidence: `README.md`)
- Admin cabinet → Shifts and scanning: manages shifts (evidence: `README.md`)
- Admin cabinet → Boxes and SSCC: manages boxes (evidence: `README.md`)
- Admin cabinet → Inventory workflows: manages inventory (evidence: `README.md`)
- Admin cabinet → Label templates: edits templates (evidence: `README.md`)
- Admin cabinet → Employee pickup: audits pickup (evidence: `README.md`)
- NestJS API → Authentication: enforces identity
- NestJS API → Code-status ingest: ingests status data (evidence: `apps/api/src/modules/chz-code-statuses/chz-code-status-ingest.service.ts`)
- NestJS API → National catalog import: supports imports (evidence: `apps/api/src/modules/national-catalog/national-catalog-import-preview.service.ts`)
- NestJS API → Billing and offers: serves billing (evidence: `README.md`)
- Billing and offers → Billing profiles: uses seller policy (evidence: `apps/api/src/modules/platform-offers/offer-preview.service.ts`)
- SaaS operator panel → NestJS API: uses
