Architecture Guide

Overview

Ajasendiri is a C interpreter with four main layers:

  1. Lexer: source text -> token stream

  2. Parser: token stream -> AST

  3. Runtime: executes AST and enforces runtime typing

  4. CLI: entrypoints for run/check/test/fmt/repl/debug/mmk

Execution flow

Typical execution path:

  1. src/cli/main.c reads command and source.

  2. src/lexer/lexer.c tokenizes the source.

  3. src/parser/parser.c builds AST (via parser submodules).

  4. src/runtime/runtime.c executes using runtime submodules.

  5. Errors return to CLI with context.

Source map

Core headers

  • include/core/token.h

  • include/core/ast.h

  • include/core/api.h

  • include/ajasendiri.h

Lexer

  • src/lexer/lexer.c

Parser

  • src/parser/parser.c (entrypoint)

  • src/parser/base.c (shared parser utilities)

  • src/parser/expr.c (expression grammar)

  • src/parser/stmt.c (statement grammar)

  • src/parser/decl.c (declarations, import/export)

Runtime composition wrappers

  • src/runtime/runtime.c

  • src/runtime/base.c

  • src/runtime/exec.c

  • src/runtime/builtins.c

Runtime core modules

  • src/runtime/base/core_types_and_values.c

  • src/runtime/base/containers_env_debug.c

  • src/runtime/base/runtime_core_and_modules.c

  • src/runtime/modules.c

  • src/runtime/typecheck.c

Runtime execution modules

  • src/runtime/exec/eval_expr.c

  • src/runtime/exec/exec_stmt_and_runtime.c

  • src/runtime/exec/public_api.c

Runtime builtins modules

  • src/runtime/builtins/value_cast_json.c

  • src/runtime/builtins/functions_kostroutine_math_time.c

  • src/runtime/builtins/native_json_fs_path_regex_http_parse.c

  • src/runtime/builtins/http_transport_and_rand.c

  • src/runtime/builtins/native_stdlib_calls.c

  • src/runtime/builtins/call_dispatch.c

CLI modules

  • src/cli/main/shared_utils_and_dep_parse.c

  • src/cli/main/project_io_and_registry.c

  • src/cli/main/repl_debug_format.c

  • src/cli/main/mmk_core_commands.c

  • src/cli/main/mmk_advanced_and_main.c

Where to put new code

  • New syntax/tokens: lexer + parser + core headers.

  • New runtime semantics: src/runtime/exec and src/runtime/base.

  • New builtin/native module behavior: src/runtime/builtins and src/runtime/modules.c.

  • New CLI/tooling behavior: src/cli/main.

Contributor guidelines

  • Use descriptive filenames by responsibility.

  • Keep composition wrappers (base.c, exec.c, builtins.c, main.c) focused on includes/wiring.

  • Add or update tests in tests/spec/pass and tests/spec/fail.

  • Update docs when behavior changes.

Builtin extension checklist

  1. Register/export symbol in src/runtime/modules.c.

  2. Implement behavior in the matching runtime builtin module.

  3. Add pass/fail tests under tests/spec.

  4. Update docs/stdlib.rst and DEV.rst.