Getting Started

Table of contents

  1. Prerequisites
  2. Option 1 — Local development
    1. 1. Clone the repository
    2. 2. Backend setup
    3. 3. Configure environment
    4. 4. Start the backend
    5. 5. Frontend setup (optional)
  3. Option 2 — Docker Compose (recommended for production testing)
  4. Using nCode
    1. Upload a workflow
    2. Generated ZIP structure
    3. API endpoints
  5. Running Tests
  6. Next Steps

Prerequisites

Requirement Version
Python 3.10+
Node.js 18+
Docker (optional) 24+

Option 1 — Local development

1. Clone the repository 

git clone https://github.com/opsingh861/nCode.git
cd nCode

2. Backend setup 

cd backend
python -m venv .venv

# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# macOS / Linux
source .venv/bin/activate

pip install -r ../requirements.txt

3. Configure environment 

cp .env.example .env
# Edit .env if you need custom settings (all values have safe defaults)

4. Start the backend 

# From the repo root
uvicorn backend.main:app --reload --port 8000

The OpenAPI docs are available at http://localhost:8000/docs.

5. Frontend setup (optional)

The frontend is a React + Vite app that proxies API calls to :8000.

cd frontend
npm install
npm run dev
# Open http://localhost:5173

Option 2 — Docker Compose (recommended for production testing)

Starts the FastAPI backend and the Nginx-served React frontend together:

docker compose up --build
Service URL
Frontend http://localhost:3000
Backend API http://localhost:8000
API docs http://localhost:8000/docs

Using nCode

Upload a workflow

  1. Open the UI (or use the API directly).
  2. Drag-and-drop or browse to your workflow.json export from n8n.
  3. Click Generate.
  4. Preview the generated Python code in the right panel.
  5. Click Download ZIP to get the full project artifact.

Generated ZIP structure 

workflow_<name>/
├── main.py             # Generated Python workflow
├── requirements.txt    # Inferred package dependencies
├── .env.example        # Credential placeholder template
└── README.md           # Quickstart notes for the generated workflow

API endpoints

Method Endpoint Description
GET / Health check
POST /api/upload Upload workflow JSON → returns code preview + download_id
GET /api/download/{id} Download ZIP artifact
GET /api/supported-nodes Lists all registered node type strings 
# Upload
curl -X POST http://localhost:8000/api/upload -F "file=@workflow.json"

# Download (replace <id> with the download_id from the response)
curl -L http://localhost:8000/api/download/<id> -o workflow.zip

Running Tests 

# Activate the backend venv, then from the repo root:
backend\.venv\Scripts\python.exe -m pytest backend/tests/ -v

All four test modules run in a few seconds and require no external services.

Next Steps

  • Read the Architecture page to understand the transpiler pipeline.
  • Browse Node Handlers to see which n8n nodes are supported.
  • Check out Contributing to submit a new handler or bug fix.