WALKTHROUGH.md

Latha DB: The Deep Dive Walkthrough

This guide takes you on a journey through the codebase, tracing the lifecycle of the application from startup to query execution.

1. The Entry Point (Main.java)

Unless running in a container, everything starts at com.lathadb.Main.

System Setup

Before any UI is shown, we perform critical environment patches:

• GraalVM Fix: We explicitly set java.home to ensure native image compatibility.
• FlatLaf: We initialize the FlatLightLaf library to give Swing a modern, flat aesthetic.

Mode Selection

Latha DB is a chameleon. Based on the arguments, it morphs:

• java -jar latha.jar --server: Boots LathaServer, skipping the UI entirely for headless deployments.
• (Default): Boots LathaWindow, the Swing-based GUI for interactive use.

---

2. The Query Lifecycle (The "Hot Path")

What happens when you type SELECT * FROM Users?

Step 1: Input

The user types the command into the Query Explorer text area in LathaWindow.

Step 2: Transpilation (SQLTranslator.java)

Because the core engine only speaks Lisp, we must translate.

• Detection: The translator checks if the string starts with SELECT, INSERT, or CREATE.
• Regex Parsing: It uses Regex capture groups to strip out columns and table names.
• Output: SELECT * FROM Users becomes (select :all :from "Users").

Step 3: Parsing (LispParser.java)

The string is tokenized (broken into chunks) and built into an Abstract Syntax Tree (AST) of LispNode objects. (select ...) becomes a root node with children parameters.

Step 4: Execution (QueryExecutor.java)

The execute() method is the brain.

• It recursively evaluates the AST.
• It switches on the function name (e.g., select).
• It calls the Storage Engine (Table.java) to scan records, apply filters, and return a list of LathaRecords.

Step 5: Result

The result bubbles back up:

1. Text Result: A success message or record count is shown in the Console.
2. Table Update: The central JTable is refreshed with the new data.
3. Analytics: If the command was a (plot), the Analytics Dashboard renders the JFreeChart.

---

3. The Subsystems

Networking (LathaServer.java & NetworkClient.java)

• Server: Uses a CachedThreadPool to handle thousands of concurrent socket connections without blocking the main thread.
• Client: Establishes a TCP connection and spawns a background ReaderThread to listen for asynchronous PUSH notifications from the server (Real-time updates).

Visualizer (GraphVisualizerPanel.java)

The cool "Physics Graph" is a simulation loop.

• The Loop: A Swing Timer fires ~60 times a second.
• Physics:
  1. Repulsion: All nodes push away from each other so they don't overlap.
  2. Attraction: Connected nodes pull toward each other like springs.
  3. Gravity: A gentle force pulls everything to the center so the graph doesn't fly off-screen.