Typegen Server

Core code generation and schema engine for Typegen
Fast • Secure • Extensible

---

🗄️ Typegen Server

The Typegen Server is the core backend service of the Typegen platform. It is responsible for database schema introspection, validation, and deterministic code generation across supported languages and styles. The API exposes generation capabilities used by the CLI and Dashboard while enforcing strict option schemas, security controls, and runtime validation.

Important: The Typegen Server can be run as a standalone service, but the recommended best practice is to manage its lifecycle, configuration, and runtime using (typegenctl) and the UI Dashboard, which provide a safer and more convenient control plane for the entire Typegen ecosystem.

How to use	Description
Typegenctl	Typegenctl GitHub
Typegen UI	Typegen-Dashboard GitHub

✨ Features

• Current Support Database Connection: MySQL/Mariadb, MSSQL, and PostgreSQL.
• Code Generation:
  • Typescript: DTOs and Zod schemas.
  • Java: Records and DTOs.
  • Mappers: Java XML and Annotation-based mappers.
  • Go: Structs
  • Python: Pydantic models, dataclasses, TypedDicts, and plain classes
• Security: Rate limiting, and CORS support.
• Health Monitoring: Integrated health check endpoints.

---

🐋 Docker Image

Pre-built Docker images are available for this project and can be pulled from the registry:

docker pull ghcr.io/khanalsaroj/typegen-server:latest

🚀 Quick Start with Docker Compose

The simplest way to run both the backend and frontend together is using Docker Compose.

Create a docker-compose.yml file with the following content:

services:
  frontend:
    image: ghcr.io/khanalsaroj/typegen-ui:latest
    container_name: typegen-frontend
    ports:
      - "7359:80"
    environment:
      - API_UPSTREAM=typegen-backend
    networks:
      - bridge-net
    restart: unless-stopped

  backend:
    image: ghcr.io/khanalsaroj/typegen-server:latest
    container_name: typegen-backend
    ports:
      - "8049:8080"
    environment:
      - APP_ENV=production
    volumes:
      - typegen-backend:/app/data
    networks:
      - bridge-net
    restart: unless-stopped

networks:
  bridge-net:
    driver: bridge

volumes:
  typegen-backend:

Then start both services in detached mode:

docker compose up -d

Once running, the services will be available at:

Service	URL
Frontend	http://localhost:7359
Backend	http://localhost:8049

🌐 API Endpoints (Summary)

1. GET /api/v1/health – Health Check

Response:

{
  "status": "ok",
  "version": "v1.2.3",
  "uptime": 172800,
  "database": {
    "connected": true,
    "latency": 12
  }
}

HTTP Status: 200 OK

---

2. POST /api/v1/connection/test – Test a DB Connection

Request Body Example:

{
  "dbType": "postgres",
  "host": "localhost",
  "port": 5432,
  "username": "admin",
  "password": "securepassword",
  "schemaName": "public",
  "databaseName": "mydb"
}

Response Example:

{
  "connectionId": 123,
  "message": "Connection established successfully",
  "success": true,
  "pingMs": 15,
  "tablesFound": 3,
  "sizeMb": 42.7,
  "tables": [
    {
      "name": "users",
      "columnCount": 12
    },
    {
      "name": "orders",
      "columnCount": 8
    }
  ]
}

HTTP Status: 200 OK

---

3. POST /api/v1/connection – Create a New DB Connection

Request Body Example:

{
  "dbType": "postgres",
  "host": "localhost",
  "port": 5432,
  "username": "admin",
  "password": "securepassword",
  "schemaName": "public",
  "databaseName": "mydb"
}

Response Success Example:

{
  "success": true,
  "message": "User fetched successfully",
  "connection": {
    "dbType": "postgres",
    "host": "localhost",
    "port": 5432,
    "username": "admin",
    "password": "securepassword",
    "schemaName": "public",
    "databaseName": "mydb"
  }
}

HTTP Status: 200 OK

---

Response Error Example:

{
  "success": false,
  "message": "Failed to create connection",
  "error": "user not found"
}

HTTP Status: 500 InternalServerError

---

4. GET /api/v1/connection – List All Connections

Response Example:

[
  {
    "connectionId": 101,
    "name": "main-db",
    "dbType": "postgres",
    "host": "localhost",
    "port": 5432,
    "databaseName": "mydb",
    "schemaName": "public",
    "username": "admin"
  },
  {
    "connectionId": 102,
    "name": "analytics-db",
    "dbType": "mysql",
    "host": "db.example.com",
    "port": 3306,
    "databaseName": "analytics",
    "schemaName": "default",
    "username": "root"
  }
]

HTTP Status: 200 OK

---

5. POST /api/v1/type – Generate Code Types

Request Body Example:

Note: The options object is dynamic. Its available fields differ depending on the chosen language and style, as each combination exposes its own configuration options. For the full list of supported options, see the documentation here.

{
  "connectionId": 102,
  "options": {
    "getter": true,
    "setter": true,
    "noArgsConstructor": true,
    "allArgsConstructor": true,
    "builder": true,
    "data": true,
    "swaggerAnnotations": true,
    "serializable": true,
    "jacksonAnnotations": true,
    "extraSpacing": true
  },
  "prefix": "Foo",
  "suffix": "Response",
  "style": "DTO",
  "language": "java",
  "tableNames": [
    "users",
    "orders"
  ]
}

Response Example:

"generated message"

HTTP Status: 200 OK

---

6. POST /api/v1/mapper – Generate Mappers

Request Body Example:

{
  "connectionId": 123,
  "options": {
    "allCrud": true
  },
  "prefix": "Db",
  "suffix": "Type",
  "style": "struct",
  "language": "go",
  "tableNames": [
    "users",
    "orders"
  ]
}

Response Example:

"generated message"

HTTP Status: 200 OK

---

🔍 Contact

• Issues: Report bugs and feature requests
• Developer: Khanal Saroj (waytosarojkhanal@gmail.com)