Arquitectura de PyGo

Arquitectura

PyGo es un framework full-stack monolítico que combina el rendimiento de Go con la flexibilidad de Python, todo detrás de un DSL isomórfico unificado.

Vista General de la Arquitectura

┌─────────────────────────────────────────────────────┐
│                    Navegador Cliente                 │
│  (UI impulsada por HTMX, sin framework JS cliente)   │
└──────────────┬──────────────────────────────────────┘
               │ HTTP (net/http)
┌──────────────▼──────────────────────────────────────┐
│               Runtime Go (servidor net/http)          │
│  - Servidor HTTP nativo (sin Gin, Echo, Fiber)       │
│  - Genera gen_go.go desde DSL .pgo                   │
│  - Codificador/decodificador MessagePack             │
│  - Cliente de Socket de Dominio Unix (UDS)           │
└──────────────┬──────────────────────────────────────┘
               │ MessagePack sobre UDS
┌──────────────▼──────────────────────────────────────┐
│              Runtime Python (intérprete)              │
│  - Python stdlib únicamente (sin Django, Flask)      │
│  - gen_py.py: código Python 1:1 desde DSL .pgo       │
│  - AST visitor para transpilación                    │
│  - SQLite/PostgreSQL vía stdlib sqlite3/psycopg      │
└──────────────┬──────────────────────────────────────┘
               │ Consultas DB (sqlite3/psycopg)
┌──────────────▼──────────────────────────────────────┐
│               Base de Datos (SQLite / PostgreSQL)     │
│  - SQL con generación automática de JOINs            │
│  - Manejo de relaciones ForeignKey                   │
│  - Migraciones automáticas desde .pgo                │
└─────────────────────────────────────────────────────┘

Componentes Clave

1. DSL .pgo

El archivo .pgo es la única fuente de verdad. Es isomórfico a Python — lo que significa:

• gen_py.py: Genera código Python 1:1 (sintaxis e semántica idénticas)
• gen_go.go: Genera mecánicamente código Go (determinista desde AST)

Ejemplo de archivo .pgo:

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)

El transpiler usa un AST visitor en Go para:

1. Parsear el archivo .pgo en un AST (parser en Go)
2. Generar gen_py.py — código Python 1:1
3. Generar gen_go.go — código Go mecánico

El patrón visitor garantiza extensibilidad — nuevas características del DSL pueden agregarse sin romper los generadores existentes.

3. Runtime Go

• Sirve peticiones HTTP vía net/http (nativo, sin router externo)
• Genera código Go que registra rutas y delega a Python vía UDS
• Se comunica con Python vía MessagePack sobre Sockets de Dominio Unix (UDS)

4. Runtime Python

• Ejecuta el código gen_py.py generado
• Maneja lógica de negocio, ORM y validación de tipos
• Usa únicamente Python stdlib — sin frameworks pesados (sin Django, Flask, SQLAlchemy)

Principios de Diseño

1. Sin frameworks pesados: Go usa net/http + database/sql; Python usa stdlib solamente.
2. Isomorfismo 1:1: El DSL .pgo se mapea directamente a Python y se convierte mecánicamente a Go.
3. MessagePack + UDS interop: Go y Python se comunican eficientemente vía protocolo binario sobre sockets Unix.
4. HTMX-first UI: HTML impulsado por el servidor con HTMUX — ni React, Vue ni Svelte.
5. DevX ultraligero: Configuración mínima, iteración rápida, tipado seguro de extremo a extremo.

Despliegue en Producción

Para producción, PyGo soporta:

• PyOxidizer: Empaqueta el runtime de Python en un binario único de Go vía pygo build --embed-python
• Despliegue binario único: Un ejecutable con intérprete Python embebido

Estructura del Proyecto

pygo/
├── cli/              # Comandos CLI (new, dev, gen, build, test)
├── core/
│   ├── transpiler/   # Parser, lexer, AST, generadores de código
│   │   ├── lexer/
│   │   ├── parser/
│   │   ├── ast/
│   │   └── generators/    # gen_go.go, gen_py.py
│   └── runtime/      # Módulos runtime Python (db, validators, jobs)
├── cmd/pygo/         # Punto de entrada
├── examples/         # Aplicaciones de ejemplo
│   ├── hello-world/
│   └── blog/
├── templates/        # Plantillas de scaffolding
└── install.sh        # Instalador de dependencias Python

Próximos Pasos

• Conceptos Clave
• Instalación
• Característica: Enum Types