# flintvn/flintjvm architecture

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

- Interactive diagram: https://gitdiagram.com/flintvn/flintjvm
- Repository: https://github.com/flintvn/flintjvm

## Overview

#### Purpose and entry points
Flint is a C++ embedded Java-like virtual machine with native bindings for core runtime APIs, graphics, networking, storage, and RTOS/platform services. The VM public surface and likely integration entry point are `vm/inc/flint.h` and `vm/src/flint.cpp`; platform adopters supply system implementations modeled by `template/src/flint_system_api.cpp`.

#### VM lifecycle and execution
The VM coordinates class loading, object/runtime state, threading, native dispatch, and bytecode execution. `vm/src/flint_execution.cpp` is the interpreter/execution core; `vm/src/flint.cpp` owns top-level VM behavior; `vm/src/flint_java_thread.cpp` represents managed Java threads. Execution crosses into platform and native layers through `vm/src/flint_native_interface.cpp`.

#### Class, bytecode, and archive loading
Class metadata is parsed and retained through class-loader, constant-pool, field, and method subsystems. `vm/src/flint_class_loader.cpp`, `vm/src/flint_java_class.cpp`, and `vm/src/flint_const_pool.cpp` form the class-definition path. Input may come from raw files or ZIP/JAR-like archives via `vm/src/flint_file_reader.cpp` and `vm/src/flint_zip_file_reader.cpp`, creating a boundary between application artifacts/storage and VM-internal representations.

#### Managed object model and runtime services
Objects, arrays, strings, throwables, and dictionaries provide the VM’s managed runtime substrate. Key implementations are `vm/src/flint_java_object.cpp`, `vm/src/flint_array_object.cpp`, and `vm/src/flint_java_string.cpp`. These structures are consumed by the interpreter and native-interface boundary, where native code must preserve VM object/reference conventions.

#### Native Java API implementation
Native methods implement the Java-facing base library in C++. Shared binding infrastructure is in `native/common/src/flint_native.cpp` and `native/common/src/flint_native_common.cpp`. Core native APIs—object/class behavior, strings, files, math, reflection, and threading—reside under `native/base/src/flint_native_object.cpp`, `native/base/src/flint_native_string.cpp`, and `native/base/src/flint_native_thread.cpp`.

#### Graphics and networking extensions
Optional native domains extend the runtime beyond base APIs. Software RGB565 graphics, fixed-point support, and Java graphics bindings are implemented by `native/draw/src/flint_native_graphics.cpp`, `native/draw/src/flint_native_rgb565_graphics.cpp`, and `native/draw/src/flint_rgb565_sw_gfx.cpp`. Socket, datagram, address, and stream bindings are implemented in `native/net/src/flint_native_flint_socket_impl.cpp`, `native/net/src/flint_native_flint_datagram_socket_impl.cpp`, and `native/net/src/flint_native_flint_socket_input_stream.cpp`.

#### Platform abstraction and deployed runtime
The VM depends on system API abstractions for OS/platform operations, configured through `template/inc/flint_conf.h` and implemented by adopters. The provided embedded deployment targets FreeRTOS, FatFs, and lwIP: `impl/src/freertos_system_thread_api.cpp`, `impl/src/fatfs_system_io_api.cpp`, and `impl/src/lwip_system_net_api.cpp`. Control flows from VM/native APIs to these adapters, isolating platform-specific scheduling, filesystem I/O, and network stacks from interpreter code.

Main entry points: [`template/src/flint_system_api.cpp`](https://github.com/flintvn/flintjvm/blob/master/template/src/flint_system_api.cpp) (System API Contract), [`vm/src/flint.cpp`](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint.cpp) (VM Lifecycle), [`vm/src/flint_execution.cpp`](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_execution.cpp) (Bytecode Interpreter), [`native/common/src/flint_native.cpp`](https://github.com/flintvn/flintjvm/blob/master/native/common/src/flint_native.cpp) (Native Binding Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_vm["VM Core"]
  node_public_api["VM Public API<br/>C++ API<br/>[flint.h]"]
  node_vm_lifecycle["VM Lifecycle<br/>VM coordinator<br/>[flint.cpp]"]
  node_interpreter["Bytecode Interpreter<br/>execution core"]
  node_managed_threads["Managed Threads<br/>thread runtime"]
  node_native_boundary{{"Native Interface<br/>dispatch boundary"}}
  node_class_loading["Class Loading<br/>class definition"]
  node_class_metadata[("Class &amp; Constant Pool<br/>metadata runtime")]
  node_artifact_readers["Artifact Readers<br/>file/archive input"]
  node_managed_objects[("Managed Objects<br/>object runtime")]
end

subgraph group_native["Native APIs"]
  node_native_common["Native Binding Core<br/>binding infrastructure<br/>[flint_native.cpp]"]
  node_base_apis["Base Native APIs<br/>core Java bindings"]
  node_graphics_apis["Graphics Bindings<br/>optional native API"]
  node_network_apis["Network Bindings<br/>optional native API"]
end

subgraph group_platform["Platform Integration"]
  node_system_contract{{"System API Contract<br/>platform abstraction"}}
  node_rtos_adapter["FreeRTOS Adapter<br/>thread platform API"]
  node_storage_adapter["FatFs Adapter<br/>filesystem platform API"]
  node_network_adapter["lwIP Adapter<br/>network platform API"]
end

node_public_api -->|"creates and controls"| node_vm_lifecycle
node_vm_lifecycle -->|"runs"| node_interpreter
node_vm_lifecycle -->|"loads classes"| node_class_loading
node_vm_lifecycle -->|"manages"| node_managed_threads
node_interpreter -->|"operates on"| node_managed_objects
node_interpreter -->|"invokes native methods"| node_native_boundary
node_class_loading -->|"reads artifacts"| node_artifact_readers
node_class_loading -->|"builds"| node_class_metadata
node_interpreter -->|"resolves bytecode symbols"| node_class_metadata
node_native_boundary -->|"dispatches through"| node_native_common
node_native_common -->|"supports"| node_base_apis
node_native_common -->|"supports"| node_graphics_apis
node_native_common -->|"supports"| node_network_apis
node_native_boundary -->|"preserves references"| node_managed_objects
node_vm_lifecycle -->|"uses platform services"| node_system_contract
node_base_apis -->|"uses system APIs"| node_system_contract
node_graphics_apis -->|"uses platform services"| node_system_contract
node_network_apis -->|"uses network services"| node_system_contract
node_system_contract -->|"thread implementation"| node_rtos_adapter
node_system_contract -->|"I/O implementation"| node_storage_adapter
node_system_contract -->|"network implementation"| node_network_adapter

click node_public_api "https://github.com/flintvn/flintjvm/blob/master/vm/inc/flint.h"
click node_vm_lifecycle "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint.cpp"
click node_interpreter "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_execution.cpp"
click node_managed_threads "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_java_thread.cpp"
click node_native_boundary "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_native_interface.cpp"
click node_class_loading "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_class_loader.cpp"
click node_class_metadata "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_java_class.cpp"
click node_artifact_readers "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_zip_file_reader.cpp"
click node_managed_objects "https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_java_object.cpp"
click node_native_common "https://github.com/flintvn/flintjvm/blob/master/native/common/src/flint_native.cpp"
click node_base_apis "https://github.com/flintvn/flintjvm/blob/master/native/base/src/flint_native_object.cpp"
click node_graphics_apis "https://github.com/flintvn/flintjvm/blob/master/native/draw/src/flint_native_graphics.cpp"
click node_network_apis "https://github.com/flintvn/flintjvm/blob/master/native/net/src/flint_native_flint_socket_impl.cpp"
click node_system_contract "https://github.com/flintvn/flintjvm/blob/master/template/src/flint_system_api.cpp"
click node_rtos_adapter "https://github.com/flintvn/flintjvm/blob/master/impl/src/freertos_system_thread_api.cpp"
click node_storage_adapter "https://github.com/flintvn/flintjvm/blob/master/impl/src/fatfs_system_io_api.cpp"
click node_network_adapter "https://github.com/flintvn/flintjvm/blob/master/impl/src/lwip_system_net_api.cpp"

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_public_api,node_vm_lifecycle,node_interpreter,node_managed_threads,node_native_boundary,node_class_loading,node_class_metadata,node_artifact_readers,node_managed_objects toneBlue
class node_native_common,node_base_apis,node_graphics_apis,node_network_apis toneAmber
class node_system_contract,node_rtos_adapter,node_storage_adapter,node_network_adapter toneMint
```

## Components

### VM Core

Managed execution and class runtime.

- [VM Public API](https://github.com/flintvn/flintjvm/blob/master/vm/inc/flint.h): C++ API · Integration entry point for VM adopters. · `vm/inc/flint.h`
- [VM Lifecycle](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint.cpp): VM coordinator · Owns top-level VM behavior and runtime coordination. · `vm/src/flint.cpp`
- [Bytecode Interpreter](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_execution.cpp): execution core · Executes managed Java bytecode. · `vm/src/flint_execution.cpp`
- [Managed Threads](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_java_thread.cpp): thread runtime · `vm/src/flint_java_thread.cpp`
- [Native Interface](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_native_interface.cpp): dispatch boundary · Crosses between managed execution and C++ native methods. · `vm/src/flint_native_interface.cpp`
- [Class Loading](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_class_loader.cpp): class definition · Builds class metadata from application artifacts. · `vm/src/flint_class_loader.cpp`
- [Class & Constant Pool](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_java_class.cpp): metadata runtime · `vm/src/flint_java_class.cpp`
- [Artifact Readers](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_zip_file_reader.cpp): file/archive input · Reads raw class files and ZIP/JAR-like archives. · `vm/src/flint_zip_file_reader.cpp`
- [Managed Objects](https://github.com/flintvn/flintjvm/blob/master/vm/src/flint_java_object.cpp): object runtime · Object, array, string, and throwable substrate. · `vm/src/flint_java_object.cpp`

### Native APIs

C++ implementations of Java-facing bindings.

- [Native Binding Core](https://github.com/flintvn/flintjvm/blob/master/native/common/src/flint_native.cpp): binding infrastructure · Shared native method support and conventions. · `native/common/src/flint_native.cpp`
- [Base Native APIs](https://github.com/flintvn/flintjvm/blob/master/native/base/src/flint_native_object.cpp): core Java bindings · Object, string, file, math, reflection, and thread natives. · `native/base/src/flint_native_object.cpp`
- [Graphics Bindings](https://github.com/flintvn/flintjvm/blob/master/native/draw/src/flint_native_graphics.cpp): optional native API · Java graphics bindings and RGB565 software rendering. · `native/draw/src/flint_native_graphics.cpp`
- [Network Bindings](https://github.com/flintvn/flintjvm/blob/master/native/net/src/flint_native_flint_socket_impl.cpp): optional native API · Socket, datagram, address, and stream bindings. · `native/net/src/flint_native_flint_socket_impl.cpp`

### Platform Integration

Adopter-provided system services and embedded adapters.

- [System API Contract](https://github.com/flintvn/flintjvm/blob/master/template/src/flint_system_api.cpp): platform abstraction · Configuration and adopter-supplied system implementation model. · `template/src/flint_system_api.cpp`
- [FreeRTOS Adapter](https://github.com/flintvn/flintjvm/blob/master/impl/src/freertos_system_thread_api.cpp): thread platform API · `impl/src/freertos_system_thread_api.cpp`
- [FatFs Adapter](https://github.com/flintvn/flintjvm/blob/master/impl/src/fatfs_system_io_api.cpp): filesystem platform API · `impl/src/fatfs_system_io_api.cpp`
- [lwIP Adapter](https://github.com/flintvn/flintjvm/blob/master/impl/src/lwip_system_net_api.cpp): network platform API · `impl/src/lwip_system_net_api.cpp`

## Connections

- VM Public API → VM Lifecycle: creates and controls
- VM Lifecycle → Bytecode Interpreter: runs
- VM Lifecycle → Class Loading: loads classes
- VM Lifecycle → Managed Threads: manages
- Bytecode Interpreter → Managed Objects: operates on
- Bytecode Interpreter → Native Interface: invokes native methods
- Class Loading → Artifact Readers: reads artifacts
- Class Loading → Class & Constant Pool: builds
- Bytecode Interpreter → Class & Constant Pool: resolves bytecode symbols
- Native Interface → Native Binding Core: dispatches through
- Native Binding Core → Base Native APIs: supports
- Native Binding Core → Graphics Bindings: supports
- Native Binding Core → Network Bindings: supports
- Native Interface → Managed Objects: preserves references
- VM Lifecycle → System API Contract: uses platform services
- Base Native APIs → System API Contract: uses system APIs
- Graphics Bindings → System API Contract: uses platform services
- Network Bindings → System API Contract: uses network services
- System API Contract → FreeRTOS Adapter: thread implementation
- System API Contract → FatFs Adapter: I/O implementation
- System API Contract → lwIP Adapter: network implementation