PyGo Architecture

Architecture

PyGo is a monolithic full-stack framework that combines the performance of Go with the flexibility of Python, all behind a unified isomorphic DSL.

Architecture Overview

┌─────────────────────────────────────────────────────┐
│                    Client Browser                    │
│  (HTMX-driven UI, no client-side JS framework)       │
└──────────────┬──────────────────────────────────────┘
               │ HTTP (net/http)
┌──────────────▼──────────────────────────────────────┐
│               Go Runtime (net/http server)           │
│  - Native HTTP server (no Gin, Echo, or Fiber)       │
│  - Generates gen_go.go from .pgo DSL                  │
│  - MessagePack encoder/decoder                        │
│  - Unix Domain Socket (UDS) client                    │
└──────────────┬──────────────────────────────────────┘
               │ MessagePack over UDS
┌──────────────▼──────────────────────────────────────┐
│              Python Runtime (interpreter)             │
│  - Python stdlib only (no Django, Flask, SQLAlchemy) │
│  - gen_py.py: 1:1 Python code from .pgo DSL          │
│  - AST visitor for transpilation                     │
│  - SQLite/PostgreSQL via stdlib sqlite3/psycopg      │
└──────────────┬──────────────────────────────────────┘
               │ Database queries (sqlite3/psycopg)
┌──────────────▼──────────────────────────────────────┐
│               Database (SQLite / PostgreSQL)          │
│  - SQL with automatic JOIN generation                 │
│  - ForeignKey relationship handling                   │
│  - Auto-migrations from .pgo model definitions       │
└─────────────────────────────────────────────────────┘

Key Components

1. `.pgo` DSL

The .pgo file is the single source of truth. It is isomorphic to Python — meaning:

gen_py.py: Generates 1:1 Python code (identical syntax and semantics)
gen_go.go: Mechanically generates Go code (deterministic from AST)

Example .pgo file:

enum Status:
  active
  inactive
  pending

model User:
  id: UUID
  email: Email
  name: String
  status: Status
  tags: Array[String]
  metadata: Map[String]String
  created: DateTime

handler greet:
  greet(name: String) -> String:
    return f"Hello, {name}!"

route GET /hello/:name -> greet

2. AST Visitor (Transpiler)

The transpiler uses a Go AST visitor to:

Parse the .pgo file into an AST (Go-side parser)
Generate gen_py.py — 1:1 Python code
Generate gen_go.go — Mechanical Go code

The AST visitor pattern ensures extensibility — new DSL features can be added without breaking existing generators.

3. Go Runtime

Serves HTTP requests via net/http (native, no external router)
Generates Go code that registers routes and delegates to Python via UDS
Communicates with Python via MessagePack over Unix Domain Sockets (UDS)

4. Python Runtime

Executes the generated gen_py.py code
Handles business logic, ORM, and type validation
Uses only Python stdlib — no heavy frameworks (no Django, Flask, SQLAlchemy)

Design Principles

Zero heavy frameworks: Go uses net/http + database/sql; Python uses stdlib only.
1:1 isomorphism: The .pgo DSL maps directly to Python and is mechanically converted to Go.
MessagePack + UDS interop: Go and Python communicate efficiently via binary protocol over Unix sockets.
HTMX-first UI: Server-driven HTML with HTMX — no React, Vue, or Svelte.
Ultra-light devx: Minimal setup, fast iteration, type-safe from end to end.

Production Deployment

For production, PyGo supports:

PyOxidizer: Bundles the Python runtime into a single Go binary via pygo build --embed-python
Single binary deploy: One executable with embedded Python interpreter

Project Structure

pygo/
├── cli/              # CLI commands (new, dev, gen, build, test)
├── core/
│   ├── transpiler/   # Parser, lexer, AST, code generators
│   │   ├── lexer/
│   │   ├── parser/
│   │   ├── ast/
│   │   └── generators/    # gen_go.go, gen_py.go
│   └── runtime/      # Python runtime modules (db, validators, jobs)
├── cmd/pygo/         # Entry point
├── examples/         # Example applications
│   ├── hello-world/
│   └── blog/
├── templates/        # Project scaffolding templates
└── install.sh        # Python dependency installer