# miraj0/oj_x architecture

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

- Interactive diagram: https://gitdiagram.com/miraj0/oj_x
- Repository: https://github.com/miraj0/oj_x

## Overview

oj_x Database Engine is a memory-mapped chunk store exposed through a single HTTP endpoint. A client submits an operation type; the endpoint dispatches insert, delete, raw-read, chain-read, or integer-insert requests to the database engine and returns the result. The engine initializes mapped storage and a free-index list, allocates chunks as needed, and persists changes asynchronously. The README documents these capabilities; the sampled source confirms the endpoint and storage calls.

Main entry points: [`server/all_routes/main.cpp`](https://github.com/miraj0/oj_x/blob/main/server/all_routes/main.cpp) (Ask endpoint), [`server/data_base/data.bin`](https://github.com/miraj0/oj_x/blob/main/server/data_base/data.bin) (Mapped data file), [`server/data_base/database.cpp`](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp) (Block allocator), [`server/data_base/server_context.h`](https://github.com/miraj0/oj_x/blob/main/server/data_base/server_context.h) (Server context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_endpoint["Ask endpoint<br/>[main.cpp]"]
end

subgraph group_engine["Database Engine"]
  node_init["DB initialization<br/>[database.cpp]"]
  node_allocator["Block allocator<br/>[database.cpp]"]
  node_insert["Payload insert<br/>[database.cpp]"]
  node_delete["Chunk delete<br/>[database.cpp]"]
  node_rawread["Raw chunk read<br/>[database.cpp]"]
  node_chainread["Chain read<br/>[database.cpp]"]
  node_intinsert["Integer insert<br/>[database.cpp]"]
  node_context["Server context<br/>[server_context.h]"]
end

subgraph group_storage["Persistent Storage"]
  node_datafile[("Mapped data file<br/>[data.bin]")]
  node_freefile[("Free-index file<br/>[free_index.bin]")]
end

node_client(("API client"))

node_client -->|"sends request"| node_endpoint
node_endpoint -->|"initializes at startup"| node_init
node_endpoint -->|"dispatches type 1"| node_insert
node_endpoint -->|"dispatches type 2"| node_delete
node_endpoint -->|"dispatches type 3"| node_rawread
node_endpoint -->|"dispatches type 4"| node_chainread
node_endpoint -->|"dispatches type 5"| node_intinsert
node_init -->|"initializes"| node_context
node_init -->|"maps"| node_datafile
node_init -->|"loads indices"| node_freefile
node_insert -->|"allocates blocks"| node_allocator
node_intinsert -->|"allocates head"| node_allocator
node_allocator -->|"uses free list"| node_context
node_allocator -->|"expands mapping"| node_datafile
node_allocator -->|"updates indices"| node_freefile
node_insert -->|"writes payload"| node_datafile
node_delete -->|"follows chunk links"| node_datafile
node_delete -->|"recycles indices"| node_context
node_delete -->|"appends indices"| node_freefile
node_rawread -->|"reads chunk"| node_datafile
node_chainread -->|"reads linked chunks"| node_datafile
node_intinsert -->|"writes integer"| node_datafile

click node_endpoint "https://github.com/miraj0/oj_x/blob/main/server/all_routes/main.cpp"
click node_init "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_allocator "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_insert "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_delete "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_rawread "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_chainread "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_intinsert "https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp"
click node_context "https://github.com/miraj0/oj_x/blob/main/server/data_base/server_context.h"
click node_datafile "https://github.com/miraj0/oj_x/blob/main/server/data_base/data.bin"
click node_freefile "https://github.com/miraj0/oj_x/blob/main/server/data_base/free_index.bin"

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_endpoint,node_client toneBlue
class node_init,node_allocator,node_insert,node_delete,node_rawread,node_chainread,node_intinsert,node_context toneAmber
class node_datafile,node_freefile toneMint
```

## Components

### HTTP API

- [Ask endpoint](https://github.com/miraj0/oj_x/blob/main/server/all_routes/main.cpp): `server/all_routes/main.cpp`

### Database Engine

- [DB initialization](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Block allocator](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Payload insert](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Chunk delete](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Raw chunk read](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Chain read](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Integer insert](https://github.com/miraj0/oj_x/blob/main/server/data_base/database.cpp): `server/data_base/database.cpp`
- [Server context](https://github.com/miraj0/oj_x/blob/main/server/data_base/server_context.h): `server/data_base/server_context.h`

### Persistent Storage

- [Mapped data file](https://github.com/miraj0/oj_x/blob/main/server/data_base/data.bin): `server/data_base/data.bin`
- [Free-index file](https://github.com/miraj0/oj_x/blob/main/server/data_base/free_index.bin): `server/data_base/free_index.bin`

### Other components

- **API client**

## Connections

- API client → Ask endpoint: sends request
- Ask endpoint → DB initialization: initializes at startup
- Ask endpoint → Payload insert: dispatches type 1
- Ask endpoint → Chunk delete: dispatches type 2
- Ask endpoint → Raw chunk read: dispatches type 3
- Ask endpoint → Chain read: dispatches type 4
- Ask endpoint → Integer insert: dispatches type 5
- DB initialization → Server context: initializes
- DB initialization → Mapped data file: maps
- DB initialization → Free-index file: loads indices
- Payload insert → Block allocator: allocates blocks
- Integer insert → Block allocator: allocates head
- Block allocator → Server context: uses free list
- Block allocator → Mapped data file: expands mapping
- Block allocator → Free-index file: updates indices
- Payload insert → Mapped data file: writes payload
- Chunk delete → Mapped data file: follows chunk links
- Chunk delete → Server context: recycles indices
- Chunk delete → Free-index file: appends indices
- Raw chunk read → Mapped data file: reads chunk
- Chain read → Mapped data file: reads linked chunks
- Integer insert → Mapped data file: writes integer