Advanced
Architecture

Flowa Architecture

Understanding Flowa's internal architecture helps you write better code and debug issues.

Compiler Pipeline

1. Lexer (lexer.cpp)

Tokenizes source code into tokens:

  • Keywords (let, func, if)
  • Identifiers (variable names)
  • Literals (strings, numbers)
  • Operators (+, -, ==)

2. Parser (parser.cpp)

Builds Abstract Syntax Tree (AST) using recursive descent parsing:

  • Expressions
  • Statements
  • Blocks

3. AST (ast.cpp)

Represents program structure as tree nodes.

4. Constant Folder (constant_folder.cpp)

Optimizes constant expressions at compile time:

let x = 2 + 3;  // Compiled as: let x = 5;

5. Bytecode Compiler (compiler.cpp)

Converts AST to bytecode instructions.

6. Bytecode (bytecode.cpp)

Low-level instructions for the runtime:

  • OP_LOAD_CONST
  • OP_CALL
  • OP_RETURN

Runtime Execution

Memory Manager (memory_manager.cpp)

  • Heap allocation
  • Reference counting
  • Garbage collection

Object System (object.h)

Object types:

  • Strings
  • Numbers
  • Arrays
  • Hashes
  • funcs

Environment (environment.h)

Stores variable bindings for scope management.

JIT Compiler (jit/compiler.cpp)

Translates hot bytecode paths to native x64/arm64 machine code:

  1. Hot Path Detection: Identifies frequently executed code
  2. Code Generation: Produces native instructions
  3. Register Allocation: Optimizes register usage
  4. Execution: Runs compiled native code

JIT Executor (jit/executor.cpp)

Executes compiled native code with register allocation.

JIT Assembler (jit/assembler.cpp)

Generates native machine instructions (x64/arm64).

Event Loop (event_loop.cpp)

Manages:

  • Asynchronous operations
  • HTTP server requests
  • Concurrent tasks

Scheduler (scheduler.cpp)

Schedules and executes tasks with priority queues:

  • Cron jobs
  • Periodic tasks
  • Event handlers

Module System

All modules are implemented as C++ builtins:

  • Registration: builtins.cpp registers module funcs
  • Implementation: Each module in dedicated source files
  • Global Access: Modules accessible globally (fs.readFile())
  • Dynamic Loading: Module loader for runtime loading

Built-in Modules

  • builtins_file.cpp - File system operations
  • builtins_json.cpp - JSON parsing/stringifying
  • builtins_auth.cpp - Bcrypt hashing
  • builtins_jwt.cpp - JWT tokens
  • builtins_mail.cpp - SMTP email
  • builtins_sqlite.cpp - SQLite database
  • builtins_http.cpp - HTTP server/client
  • builtins_cron.cpp - Job scheduling
  • builtins_log.cpp - Structured logging
  • builtins_os.cpp - OS interaction

Concurrency Model

Actor Model

Message-passing between actors for safe parallelism.

Event Loop

Non-blocking I/O with event queue.

Task System (task.cpp)

Schedulable units of work.

Execution Flow

Source Code
    ↓
[Lexer] → Tokens
    ↓
[Parser] → AST
    ↓
[Compiler] → Bytecode
    ↓
[Runtime] → Execution
    ↓
[JIT] → Native Code (hot paths)

Performance Optimizations

  1. JIT Compilation: Hot code → native machine code
  2. Constant Folding: Compile-time evaluation
  3. Register Allocation: Efficient CPU usage
  4. Reference Counting: Fast memory management
  5. Object Pooling: Reuse common objects

Development

Building from Source

git clone https://github.com/senapati484/flowa.git
cd flowa
./build.sh

Project Structure

flowa/
├── src/              # Source code
│   ├── lexer.cpp
│   ├── parser.cpp
│   ├── compiler.cpp
│   ├── jit/         # JIT compiler
│   └── builtins/    # Standard library
├── include/          # Headers
├── examples/         # Example programs
├── tests/           # Test suite
└── docs/            # Documentation

Contributing

See the Contributing Guide (opens in a new tab).

Version Information

  • Current Version: 0.1.6 (December 2025)
  • Language: Flowa 0.1
  • Runtime: C++17 bytecode interpreter with JIT
  • Platforms: Linux, macOS (including Apple Silicon), Windows

Next Steps

Concurrency (Actors)Examples