ENTRAN - English as Programming Language

Transform troubleshooting documentation into executable programs with a familiar debugger interface.

Quick Start

Prerequisites

• Node.js 18+
• npm or yarn

Installation & Startup

1. Clone and Setup

   git clone https://github.com/rewrlution/entran.git
   cd entran
   npm install

2. Start Backend Server (Terminal 1)

   node src/server/app.js

   Backend runs on: http://localhost:3001

3. Start Frontend (Terminal 2)

   cd frontend
   npm install
   npm start

   Frontend runs on: http://localhost:3000

4. Access Application Open browser to: http://localhost:3000

Project Structure

entran/
├── src/
│   ├── server/           # Express backend server
│   │   ├── routes/       # API endpoints (/api/*)
│   │   └── middleware/   # Validation & error handling
│   └── services/         # 4-stage compilation pipeline
│       ├── LexerService.js      # Stage 1: Markdown → AST
│       ├── TranspilerService.js # Stage 2: AST → Program
│       ├── AnalyzerService.js   # Stage 3: Semantic Analysis
│       └── ExecutionService.js  # Stage 4: Program Execution
├── frontend/             # React web application
│   ├── src/
│   │   ├── components/   # UI components (Layout, etc.)
│   │   └── pages/        # Main pages (Dashboard, Editor, etc.)
└── package.json          # Backend dependencies

4-Stage Compilation Pipeline

1. 🔍 Lexical Analysis - Parse markdown → AST using marked.js
2. 🔄 Transpilation - AST → Executable program with tool registry
3. 🧠 Semantic Analysis - Extract intent, entities & relationships
4. ⚡ Execution - Step-by-step debugging & execution

API Endpoints

Stage 1: Lexical Analysis

POST /api/lexer/parse
Content-Type: application/json
{
  "markdown": "# Troubleshooting Guide\n\n## Steps\n1. Check connectivity"
}

Stage 2: Transpilation

POST /api/transpiler/transpile
Content-Type: application/json
{
  "ast": { /* AST from stage 1 */ }
}

Stage 3: Semantic Analysis

POST /api/analyzer/analyze
Content-Type: application/json
{
  "program": { /* Program from stage 2 */ }
}

Stage 4: Execution

POST /api/execution/start
Content-Type: application/json
{
  "program": { /* Program object */ },
  "analysis": { /* Analysis from stage 3 */ }
}

Web Interface

• 📊 Dashboard - System stats, recent documents, pipeline health
• 📝 Document Editor - Upload/edit markdown, real-time processing
• 🔬 Stage Viewer - Interactive pipeline visualization & metrics
• 🎯 Execution Monitor - Step-by-step debugger with terminal

Troubleshooting

Common Issues

1. Port 3001 already in use

   lsof -ti:3001
   kill $(lsof -ti:3001)

2. React compilation warnings

   • These are non-blocking ESLint warnings
   • Application will still function normally

3. Backend connection errors

   • Ensure both servers are running
   • Check console logs for detailed errors

---

ENTRAN - English as Programming Language! 🚀

• POST /api/execute/start - Stage 4: Start program execution
• POST /api/execute/step - Execute debugging commands

Development

See docs/07-implementation-roadmap.md for detailed implementation plan.

License

MIT