docs: Add ARCHITECTURE.md

Author: vain0x

ARCHITECTURE.md

@@ -0,0 +1,68 @@
+# ARCHITECTURE
+
+(*What is ARCHITECTURE.md?* See [this article: ARCHITECTURE.md](https://matklad.github.io/2021/02/06/ARCHITECTURE.md.html).)
+
+## Code map
+
+Projects:
+
+- MiloneShared: Shared types and utils
+- MiloneSyntax: Syntax analysis and type checking
+- MiloneTransform: Code generation
+- MiloneCli: CLI app
+- MiloneLspServer: LSP server implementation (F#)
+
+Diagram of project dependencies:
+
+         Shared
+            ^
+          /   \
+         /     \
+    Syntax   Transform
+     ^  ^       ^
+     |   \     /
+     |    \   /
+     |     Cli
+    LSP
+
+Note that Transform is not depended by Syntax and LSP server.
+That illustrates modification of Transform doesn't affect interface of the language.
+
+### Data structures
+
+- Abstract Syntax Tree (AST)
+- Typed intermediate representation (TIR)
+    - Functional-style IR. For checking.
+- High-level intermediate representation (HIR)
+    - Functional-style IR. For transformation.
+- Mid-level intermediate representation (MIR)
+    - For C code generation.
+    - Imperative-style IR.
+- C intermediate representation (CIR)
+    - Similar to AST of C language.
+
+Diagram of data flow.
+
+    FileSystem (*.milone)
+      | tokenize & parse
+      v
+     AST
+      |
+      v
+     TIR -- type checking etc.
+      |
+      ~  -- Syntax / Transform boundary
+      |
+      v
+     HIR -- closure conversion etc.
+      ↓
+     MIR
+      ↓
+     CIR
+      ↓
+    FileSystem (*.c)     
+
+### Others
+
+- FSharpOnly and Program.fs is F# only part.
+- MiloneOnly is milone-lang only part.

internals.md

@@ -4,68 +4,7 @@ Notes for milone-lang developers.
 
 ## Architecture
 
-See comments written at the top of each file.
-
-Utilities:
-
-- [Util](MiloneLang/Util.fs)
-    - Utility functions for string, list etc.
-
-Domains (types and functions):
-
-- [Syntax](MiloneLang/Syntax.fs)
-    - Tokens, abstract syntax tree (AST), source location information etc.
-- [Hir](MiloneLang/Hir.fs):
-    - Functional-style intermediate representation
-- [Mir](MiloneLang/Mir.fs):
-    - Imperative-style intermediate representation
-- [Cir](MiloneLang/Cir.fs)
-    - AST of the C code to be pretty printed
-
-Program analysis:
-
-- [SyntaxTokenize](MiloneLang/SyntaxTokenize.fs) (milone-lang source code -> Token list)
-- [SyntaxParse](MiloneLang/SyntaxParse.fs) (Token list -> AST)
-- [AstToHir](MiloneLang/AstToHir.fs) (AST -> HIR)
-- [AstBundle](MiloneLang/AstBundle.fs) (\*files\* -> HIR)
-    - Loads source files of project and concatenates them into single HIR program
-- [NameRes](MiloneLang/NameRes.fs) (Name resolution) (HIR)
-- [Typing](MiloneLang/Typing.fs) (Type inference) (HIR)
-
-Transformations:
-
-- [AutoBoxing](MiloneLang/AutoBoxing.fs)
-    - Resolves recursive nominal types
-- [RecordRes](MiloneLang/RecordRes.fs)
-    - Resolves use of field names
-- [ClosureConversion](MiloneLang/ClosureConversion.fs)
-    - Resolves non-closed functions
-- [EtaExpansion](MiloneLang/EtaExpansion.fs)
-    - Resolves partial applications and function references
-- [Hoist](MiloneLang/Hoist.fs)
-    - Just a preparation of monomorphization
-- [Monomorphization](MiloneLang/Monomorphization.fs)
-    - Resolves use of generic functions by code cloning
-- [TailRecOptimizing](MiloneLang/TailRecOptimizing.fs)
-    - Marks tail-recursive calls to be optimized
-- [MirGen](MiloneLang/MirGen.fs) (HIR -> MIR)
-    - Resolves pattern matches
-- [CirGen](MiloneLang/CirGen.fs) (MIR -> CIR)
-- [CirDump](MiloneLang/CirDump.fs) (CIR -> C source code)
-
-Entrypoints:
-
-- [Cli.fs](MiloneLang/Cli.fs)
-    - CLI application logic shared by F# and milone-lang
-- [Program.fs](MiloneLang/Program.fs)
-    - .NET entrypoint
-- [MiloneLang.milone](MiloneLang/MiloneLang.milone)
-    - milone-lang entrypoint
-
-Language-specific parts:
-
-- [FSharpOnly](MiloneLang/FSharpOnly.fs)
-- [MiloneOnly](MiloneLang/MiloneOnly.milone)
+[ARCHITECTURE.md](ARCHITECTURE.md)
 
 ## Development