How pulkitjakhmola/amscode works
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: index.ts API Server · App.tsx App Shell · AMS.g4 Grammar · main.cpp CLI Driver
Components 21
AMS Lang
C++ DSL compiler/runtime and CLI driver
- Grammar · Defines the AMS language syntax
ams-lang/grammar/AMS.g4 - CodeGen · Generates executable monitoring logic from AMS programs
ams-lang/src/compiler/CodeGen.cpp - Linker · Connects compiled units into a runnable monitor
ams-lang/src/compiler/ProjectLinker.cpp - Evaluator · Interprets AMS programs directly
ams-lang/include/ams/interpreter/Evaluator.hpp - Runtime Core · Event loop, actions, watchers, and logging for monitoring execution
ams-lang/include/ams/runtime/EventLoop.hpp - CLI Driver · 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 · Main HTTP boundary for the IDE backend
IDE/server/src/index.ts - Auth · Request authentication and access control
IDE/server/src/middleware/auth.ts - Domain Routes · Auth, projects, rules, logs, ingest, parse, compile, sessions, notifications, and files
IDE/server/src/routes/projects.ts - Parser Service · Coordinates parsing and syntax/AST handling for the IDE
IDE/server/src/services/parser.ts - Sessions · Tracks live session state for connected users and monitors
IDE/server/src/services/sessions.ts - WebSockets · Pushes live updates to the UI
IDE/server/src/services/websocket.ts - Prisma DB · Database access layer for persisted IDE state
IDE/server/src/lib/prisma.ts - 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 · Top-level frontend application and routing
IDE/client/src/App.tsx - Code Editor · Monaco-based editing surface for .ams programs
IDE/client/src/components/Editor/CodeEditor.tsx - AST Panel · Displays parsed structure and diagnostics
IDE/client/src/components/ASTPanel/ASTPanel.tsx - Management Pages · Projects, rules, log sources, alert routes, and team views
IDE/client/src/pages/Projects.tsx - Compiler Hook · Client-side compile and backend request coordination
IDE/client/src/hooks/useCompiler.ts - API Client · Typed frontend access to backend endpoints
IDE/client/src/lib/api.ts - Electron Shell · Desktop runtime wrapper around the same React frontend
IDE/client/electron/main.ts
Connections 26
- 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