# pulkitjakhmola/amscode architecture

> Architecture diagram of the GitHub repository pulkitjakhmola/amscode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pulkitjakhmola/amscode
- Repository: https://github.com/pulkitjakhmola/amscode

## Overview

1. **Repo split**
   - The repository has two major subsystems with a clear boundary: `ams-lang/` is the DSL compiler/runtime, and `IDE/` is the platform/IDE around that language. The IDE does not replace the compiler; it orchestrates editing, parsing, compiling, rule management, and monitoring for `.ams` programs.

2. **AMS-Lang compiler/runtime**
   - `ams-lang/` is a C++17 project built with CMake. It uses an ANTLR4 grammar (`grammar/AMS.g4`) to define the language, then compiles or interprets `.ams` scripts into executable monitoring logic.
   - The source layout suggests a pipeline of grammar → parser/AST → code generation or evaluation. `CodeGen`, `ProjectLinker`, `Evaluator`, and runtime types like `Action`, `Watcher`, `EventLoop`, and `Logger` form the core language engine.

3. **Compiler execution model**
   - The compiler has both a command-line driver (`src/driver/main.cpp`) and runtime support for event-driven monitoring. That implies two modes: interpret a script directly or build a native executable that runs the monitoring logic independently.
   - The example scripts show the language is centered on sources, rules, time windows, and response actions.

4. **IDE backend**
   - `IDE/server/` is a Node.js + Express backend written in TypeScript. It persists application state through Prisma into PostgreSQL, with schema definitions in `prisma/schema.prisma`.
   - The backend is split into routes for domain areas: auth, projects, rules, log sources, alert routes, sessions, notifications, members, ingest, parse, compile, and filesystem operations.

5. **Backend responsibilities and boundaries**
   - The server is the main boundary between UI and data/services. It handles authentication (`middleware/auth.ts`), metadata persistence, log ingestion, compilation/parse requests, and real-time updates.
   - `services/parser.ts`, `services/sessions.ts`, and `services/websocket.ts` indicate that the backend also coordinates live parsing/session state and pushes events to the UI over WebSockets.

6. **Frontend IDE**
   - `IDE/client/` is a React 18 + Vite frontend. It is structured around an editor workspace and several management pages.
   - Core UI components include the code editor, AST panel, file explorer, toolbar, notification center, dashboard, and settings. The page layer covers auth, projects, project dashboard, rules editor, alert routes, log sources, and team management.

7. **IDE data flow**
   - The main user flow is: edit `.ams` code in the Monaco-based editor, send source/compile requests to the backend, receive diagnostics/AST information, and display results in the AST panel and output/notification areas.
   - `hooks/useCompiler.ts` and `lib/api.ts` are the likely client-side integration points for compile and backend calls, while `useSettings.ts` handles local/runtime preferences.

8. **Electron desktop shell**
   - The client also has an Electron wrapper (`client/electron/main.ts`, `preload.ts`). This means the same React app can run either in a browser or as a desktop application with a preload bridge for safer access to host capabilities.
   - The Electron path is a packaging/runtime boundary, not a separate app logic layer; it wraps the same frontend and backend services.

9. **Monitoring and ingestion flow**
   - A second important system flow is log monitoring: external log sources enter through ingest/log-source routes, are parsed or correlated by the backend and/or compiler/runtime, and then generate alerts, notifications, and dashboard metrics.
   - WebSockets are the key real-time mechanism for pushing live rule hits, stream status, and session updates back to the UI.

10. **Persistence and deployment**
   - Project metadata, rules, alert routing, and team data live in PostgreSQL via Prisma. The README indicates Docker Compose is used to bring up the database, server, and client together, with persistent storage on the host.
   - The repo also supports separate launch modes: browser-based development and Electron desktop launch. The compiler is built independently from the IDE stack, reinforcing the split between language engine and platform.

11. **Architectural takeaway**
   - The clearest diagram should show three layers: the C++ AMS language engine at the core, the Node/Prisma backend as the coordination and persistence layer, and the React/Electron frontend as the interactive workspace. Data moves from user-edited `.ams` scripts to parsing/compiling, then to monitoring/ingest, and finally to alerts and dashboards.

Main entry points: [`IDE/server/src/index.ts`](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/index.ts) (API Server), [`IDE/client/src/App.tsx`](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/App.tsx) (App Shell), [`ams-lang/grammar/AMS.g4`](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/grammar/AMS.g4) (Grammar), [`ams-lang/src/driver/main.cpp`](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/driver/main.cpp) (CLI Driver)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_lang["AMS Lang"]
  node_n_grammar["Grammar<br/>ANTLR4 DSL<br/>[AMS.g4]"]
  node_n_codegen["CodeGen<br/>compiler<br/>[CodeGen.cpp]"]
  node_n_linker["Linker<br/>compiler<br/>[ProjectLinker.cpp]"]
  node_n_evaluator["Evaluator<br/>interpreter<br/>[Evaluator.hpp]"]
  node_n_runtime(("Runtime Core<br/>event runtime<br/>[EventLoop.hpp]"))
  node_n_driver["CLI Driver<br/>entrypoint<br/>[main.cpp]"]
end

subgraph group_grp_backend["IDE Backend"]
  node_n_server["API Server<br/>express app<br/>[index.ts]"]
  node_n_auth["Auth<br/>middleware<br/>[auth.ts]"]
  node_n_routes["Domain Routes<br/>api routes<br/>[projects.ts]"]
  node_n_parse_service["Parser Service<br/>[parser.ts]"]
  node_n_sessions["Sessions<br/>[sessions.ts]"]
  node_n_ws(("WebSockets<br/>realtime<br/>[websocket.ts]"))
  node_n_prisma[("Prisma DB<br/>orm<br/>[prisma.ts]")]
  node_n_schema["Schema<br/>[schema.prisma]"]
end

subgraph group_grp_frontend["IDE Frontend"]
  node_n_client_app["App Shell<br/>react app<br/>[App.tsx]"]
  node_n_editor["Code Editor<br/>workspace<br/>[CodeEditor.tsx]"]
  node_n_ast["AST Panel<br/>visualizer<br/>[ASTPanel.tsx]"]
  node_n_pages["Management Pages<br/>screens<br/>[Projects.tsx]"]
  node_n_hooks["Compiler Hook<br/>client integration<br/>[useCompiler.ts]"]
  node_n_api["API Client<br/>client lib<br/>[api.ts]"]
  node_n_electron["Electron Shell<br/>desktop bridge<br/>[main.ts]"]
end

node_n_grammar -->|"parse model"| node_n_codegen
node_n_grammar -->|"syntax"| node_n_evaluator
node_n_driver -->|"invoke"| node_n_codegen
node_n_driver -->|"run"| node_n_evaluator
node_n_codegen -->|"emit"| node_n_linker
node_n_evaluator -->|"uses"| node_n_runtime
node_n_linker -->|"builds"| node_n_runtime
node_n_runtime -->|"executes"| node_n_driver
node_n_server -->|"protects"| node_n_auth
node_n_server -->|"mounts"| node_n_routes
node_n_server -->|"coordinates"| node_n_parse_service
node_n_server -->|"tracks"| node_n_sessions
node_n_server -->|"pushes"| node_n_ws
node_n_server -->|"persists"| node_n_prisma
node_n_prisma -->|"maps"| node_n_schema
node_n_parse_service -->|"parses with"| node_n_grammar
node_n_client_app -->|"hosts"| node_n_editor
node_n_client_app -->|"shows"| node_n_ast
node_n_client_app -->|"navigates"| node_n_pages
node_n_hooks -->|"calls"| node_n_api
node_n_editor -->|"compile"| node_n_hooks
node_n_ast -->|"diagnose"| node_n_hooks
node_n_pages -->|"loads"| node_n_api
node_n_electron -->|"wraps"| node_n_client_app
node_n_ws -->|"updates"| node_n_client_app
node_n_sessions -->|"syncs"| node_n_ws

click node_n_grammar "https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/grammar/AMS.g4"
click node_n_codegen "https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/compiler/CodeGen.cpp"
click node_n_linker "https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/compiler/ProjectLinker.cpp"
click node_n_evaluator "https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/include/ams/interpreter/Evaluator.hpp"
click node_n_runtime "https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/include/ams/runtime/EventLoop.hpp"
click node_n_driver "https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/driver/main.cpp"
click node_n_server "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/index.ts"
click node_n_auth "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/middleware/auth.ts"
click node_n_routes "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/routes/projects.ts"
click node_n_parse_service "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/services/parser.ts"
click node_n_sessions "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/services/sessions.ts"
click node_n_ws "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/services/websocket.ts"
click node_n_prisma "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/lib/prisma.ts"
click node_n_schema "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/prisma/schema.prisma"
click node_n_client_app "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/App.tsx"
click node_n_editor "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/components/Editor/CodeEditor.tsx"
click node_n_ast "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/components/ASTPanel/ASTPanel.tsx"
click node_n_pages "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/pages/Projects.tsx"
click node_n_hooks "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/hooks/useCompiler.ts"
click node_n_api "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/lib/api.ts"
click node_n_electron "https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/electron/main.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_grammar,node_n_codegen,node_n_linker,node_n_evaluator,node_n_runtime,node_n_driver toneBlue
class node_n_server,node_n_auth,node_n_routes,node_n_parse_service,node_n_sessions,node_n_ws,node_n_prisma,node_n_schema toneAmber
class node_n_client_app,node_n_editor,node_n_ast,node_n_pages,node_n_hooks,node_n_api,node_n_electron toneMint
```

## Components

### AMS Lang

C++ DSL compiler/runtime and CLI driver

- [Grammar](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/grammar/AMS.g4): ANTLR4 DSL · Defines the AMS language syntax · `ams-lang/grammar/AMS.g4`
- [CodeGen](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/compiler/CodeGen.cpp): compiler · Generates executable monitoring logic from AMS programs · `ams-lang/src/compiler/CodeGen.cpp`
- [Linker](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/compiler/ProjectLinker.cpp): compiler · Connects compiled units into a runnable monitor · `ams-lang/src/compiler/ProjectLinker.cpp`
- [Evaluator](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/include/ams/interpreter/Evaluator.hpp): interpreter · Interprets AMS programs directly · `ams-lang/include/ams/interpreter/Evaluator.hpp`
- [Runtime Core](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/include/ams/runtime/EventLoop.hpp): event runtime · Event loop, actions, watchers, and logging for monitoring execution · `ams-lang/include/ams/runtime/EventLoop.hpp`
- [CLI Driver](https://github.com/pulkitjakhmola/amscode/blob/main/ams-lang/src/driver/main.cpp): entrypoint · Command-line entry into the compiler/runtime · `ams-lang/src/driver/main.cpp`

### IDE Backend

Node/Express API, persistence, parsing, and realtime services

- [API Server](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/index.ts): express app · Main HTTP boundary for the IDE backend · `IDE/server/src/index.ts`
- [Auth](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/middleware/auth.ts): middleware · Request authentication and access control · `IDE/server/src/middleware/auth.ts`
- [Domain Routes](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/routes/projects.ts): api routes · Auth, projects, rules, logs, ingest, parse, compile, sessions, notifications, and files · `IDE/server/src/routes/projects.ts`
- [Parser Service](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/services/parser.ts): service · Coordinates parsing and syntax/AST handling for the IDE · `IDE/server/src/services/parser.ts`
- [Sessions](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/services/sessions.ts): service · Tracks live session state for connected users and monitors · `IDE/server/src/services/sessions.ts`
- [WebSockets](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/services/websocket.ts): realtime · Pushes live updates to the UI · `IDE/server/src/services/websocket.ts`
- [Prisma DB](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/src/lib/prisma.ts): orm · Database access layer for persisted IDE state · `IDE/server/src/lib/prisma.ts`
- [Schema](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/server/prisma/schema.prisma): postgres schema · Persistent models for projects, rules, alert routes, members, and related state · `IDE/server/prisma/schema.prisma`

### IDE Frontend

React workspace and Electron desktop shell

- [App Shell](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/App.tsx): react app · Top-level frontend application and routing · `IDE/client/src/App.tsx`
- [Code Editor](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/components/Editor/CodeEditor.tsx): workspace · Monaco-based editing surface for .ams programs · `IDE/client/src/components/Editor/CodeEditor.tsx`
- [AST Panel](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/components/ASTPanel/ASTPanel.tsx): visualizer · Displays parsed structure and diagnostics · `IDE/client/src/components/ASTPanel/ASTPanel.tsx`
- [Management Pages](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/pages/Projects.tsx): screens · Projects, rules, log sources, alert routes, and team views · `IDE/client/src/pages/Projects.tsx`
- [Compiler Hook](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/hooks/useCompiler.ts): client integration · Client-side compile and backend request coordination · `IDE/client/src/hooks/useCompiler.ts`
- [API Client](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/src/lib/api.ts): client lib · Typed frontend access to backend endpoints · `IDE/client/src/lib/api.ts`
- [Electron Shell](https://github.com/pulkitjakhmola/amscode/blob/main/IDE/client/electron/main.ts): desktop bridge · Desktop runtime wrapper around the same React frontend · `IDE/client/electron/main.ts`

## Connections

- Grammar → CodeGen: parse model · Grammar feeds the compile pipeline
- Grammar → Evaluator: syntax · Grammar also supports interpretation
- CLI Driver → CodeGen: invoke · CLI launches compilation
- CLI Driver → Evaluator: run · CLI can execute scripts directly
- CodeGen → Linker: emit · Compiled output is linked into a runnable monitor
- Evaluator → Runtime Core: uses · Interpreter depends on runtime event processing
- Linker → Runtime Core: builds · Linked projects target the monitoring runtime
- Runtime Core → CLI Driver: executes · Runtime can be launched from the compiler entrypoint
- API Server → Auth: protects · API routes are gated by authentication
- API Server → Domain Routes: mounts · Server exposes domain-specific route modules
- API Server → Parser Service: coordinates · Server delegates parse and AST operations
- API Server → Sessions: tracks · Server maintains live session state
- API Server → WebSockets: pushes · Server broadcasts realtime updates
- API Server → Prisma DB: persists · Server stores and loads IDE state
- Prisma DB → Schema: maps · ORM schema defines persisted entities
- Parser Service → Grammar: parses with · Backend parsing aligns with AMS syntax
- App Shell → Code Editor: hosts · Main workspace centers on the editor
- App Shell → AST Panel: shows · Parsed structure and diagnostics are displayed nearby
- App Shell → Management Pages: navigates · App routes to management screens
- Compiler Hook → API Client: calls · Compiler hook uses the shared API client
- Code Editor → Compiler Hook: compile · Editor sends source to backend compile flows
- AST Panel → Compiler Hook: diagnose · AST panel reflects parser/compiler responses
- Management Pages → API Client: loads · Management screens fetch backend data
- Electron Shell → App Shell: wraps · Desktop shell loads the same frontend app
- WebSockets → App Shell: updates · Realtime backend events reach the UI
- Sessions → WebSockets: syncs · Session state is broadcast over websockets
