docs: reorganize into en/ and bg/ subfolders with numbered indices

- New docs/index.md with language selector - docs/en/ — 01-getting-started, 02-architecture, 03-ai-integration, 04-api-reference, 05-user-guide, 06-roadmap - docs/bg/ — same structure in Bulgarian - Root README.md trimmed to quick-start + links to docs/ - Removed old flat docs/ files (ARCHITECTURE.md, AI_FIRST.md, etc.) - Added swap!/reset! examples to getting-started guides
2026-05-08 23:24:47 +03:00
parent 2b32640eeb
commit 10e4ec07d6
18 changed files with 490 additions and 443 deletions
@@ -0,0 +1,107 @@
+
+[← Към индекса](index.md)
+
+---
+
+# Архитектура на Clojure/Nim
+
+## Общ Преглед
+
+Clojure/Nim е **компилатор**, не интерпретатор. Следва модела на ClojureScript: Clojure изходният код се чете, разширява с макроси, анализира и се генерира като Nim изходен код, който после се компилира до C и накрая до native бинарен файл.
+
+## Компилационен Пайплайн
+
+```
+┌─────────────┐
+│  .clj Файл  │
+└──────┬──────┘
+       │
+  ┌────▼────┐
+  │ Reader  │  ← EDN парсер. Произвежда Clojure структури от данни.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Макроси │  ← Разширение на defmacro. Работи върху Clojure данни.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │Анализатор│  ← Специални форми, locals, анализ на closures.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Генератор│  ← Генерира Nim AST / изходен код.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │ Nim CC  │  ← Nim → C компилация.
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │   C CC  │  ← C → машинен код (GCC/Clang).
+  └────┬────┘
+       │
+  ┌────▼────┐
+  │  Бинарен│  ← Единичен native изпълним файл.
+  └─────────┘
+```
+
+## Ключови Дизайн Решения
+
+### 1. AOT Компилатор
+Компилираме предварително (ahead-of-time), като ClojureScript. Това ни дава:
+- Бързо изпълнение (скорост на C)
+- Малък размер на бинарния файл
+- Без overhead на интерпретатор
+
+Компромисът е, че компилацията в REPL е по-бавна (всяка форма се компилира индивидуално).
+
+### 2. Clojure Макроси върху Clojure Данни
+Разширяването на макроси става **преди** да стигнем до Nim. Nim никога не вижда Clojure макроси:
+
+```clojure
+(defmacro unless [condition & body]
+  `(if (not ~condition)
+     (do ~@body)))
+```
+
+Този макро оперира върху `CljVal` обекти (Clojure списъци, символи), не върху Nim AST.
+
+### 3. Runtime в Nim
+Модулът `lib/cljnim_runtime.nim` предоставя:
+- `CljVal` — tagged union, представящ всички Clojure стойности
+- `cljAdd`, `cljMul`, и т.н. — полиморфна аритметика
+- `cljRepr` — текстово представяне
+
+### 4. Nim Interop
+Вместо Java interop, имаме директен Nim interop:
+
+```clojure
+(nim/math/sin x)
+(nim/strutils/toUpper s)
+```
+
+Nim модулите се импортират автоматично при извикване през `nim/module/fn` шаблона.
+
+## Отговорности на Модулите
+
+| Модул | Роля |
+|---|---|
+| `src/reader.nim` | Парсира `.clj` текст към `CljVal` AST |
+| `src/emitter.nim` | Трансформира `CljVal` AST в Nim изходен код |
+| `src/repl.nim` | Имплементация на human и AI REPL |
+| `src/eval.nim` | Tree-walking interpreter за бързо in-memory eval |
+| `src/deps.nim` | Резолюция на зависимости (deps.edn формат) |
+| `src/core.nim` | Core runtime функции (AOT компилирани) |
+| `src/types.nim` | Типове на AST възли (използват се от reader/emitter) |
+| `src/macros.nim` | Двигател за разширяване на макроси |
+| `src/runtime.nim` | Допълнителни runtime помощници |
+| `lib/cljnim_runtime.nim` | Основна runtime библиотека |
+| `lib/cljnim_pvec.nim` | Persistent Vector (HAMT имплементация) |
+| `lib/cljnim_pmap.nim` | Persistent Hash Map (HAMT имплементация) |
+| `lib/cljnim_async.nim` | core.async channels runtime |
+
+## Модел на Паметта
+
+- Използва Nim's ORC garbage collector
+- `CljVal` е `ref object` (заделя се на heap)
+- Persistent структури от данни (Vector, Map, Set) използват структурно споделяне през HAMT