Usage

This guide covers how to use the DDK service to create and manage GraphQL servers.

Table of Contents

• Prerequisites
• Understanding the Architecture
• Creating a Server
• Creating a Server with Schema
• Regenerating a Server
• Validating Schemas
• Deleting Objects
• Testing Custom Logic
• Working with Custom Resolvers
• The Workspace Concept
• Testing Your Server
• Deployment
• Common Workflows

---

Prerequisites

Required

• Access to the SDK API (which includes the DDK service)
• PostgreSQL database (version 12+)
• Basic understanding of GraphQL
• Your schema files

Optional

• Redis (for caching)
• Docker (for containerized development)

---

Understanding the Architecture

Service Flow

The DDK operates as a service that transforms schema definitions into complete GraphQL servers. You interact with the DDK through the SDK API, which provides a GraphQL interface to the underlying code generation capabilities.

Streaming Progress

All operations provide real-time progress updates as they execute, streaming messages about the current generation step, allowing you to monitor the process as it runs.

Creating a Server

The initial server creation scaffolds a new Go server from your configuration.

What Happens

The DDK creates a complete application structure including workspace setup, server directory creation, configuration file generation, Docker setup, and optional JWT token generation.

Step 1: Prepare Your Schema

Create a schema file with your data model defining the types, fields, constraints, and relationships your application needs.

Step 2: Configure Server Creation

Provide server configuration including name, port, paths, database connection details (PostgreSQL), and optional Redis configuration.

Configuration Parameters:

• Server name and port
• Database connection details (name, host, user, password, port, schema)
• Optional Redis URL
• Authentication settings (JWT enable/disable)
• Auto-migration preferences
• Logging level
• Service name

Step 3: Monitor Generation

The DDK streams progress messages as it generates your server, showing each step of the creation process.

Step 4: Generated Output

The DDK creates a complete Go application following domain-driven design architecture with clear separation between application logic, domain models, infrastructure, and generated code.

The generated structure includes:

• Application layer with repository interfaces and services
• Domain layer for business logic
• Infrastructure layer with database connections and repositories
• GraphQL layer with schemas, models, and resolvers
• Server layer with middleware and routing
• Complete Docker setup
• Database migration configuration
• Testing scaffolding

---

Creating a Server with Schema

This method combines server creation with schema processing in a single operation, creating a fully functional server ready to use.

What Happens

The system validates your schema, creates the server structure, generates CRUD resolvers for all types, processes relationships, generates GraphQL runtime code, creates Docker configuration, and optionally starts the server.

Default Resolver Generation

The DDK automatically generates CRUD resolvers based on the operations you specify in your schema directives. For each type, it creates the appropriate queries and mutations according to your requirements.

The system parses type definitions, maps GraphQL types to appropriate input types, creates standard query and mutation entries, and adds pagination and sorting support for list queries.

---

Regenerating a Server

When you update your schema, use regeneration instead of creating from scratch. This is the primary method for iterating on an existing server.

When to Regenerate

• Schema changes: Adding or removing types and fields
• Relationship updates: Modifying entity connections
• Constraint changes: Updating validation rules
• Custom resolver additions: Adding new custom operations

What Happens

The regeneration pipeline includes multiple phases: schema validation, resolver generation, schema placement, workspace migration, code generation, plugin execution, mock generation, and reverse migration of generated code back to the workspace.

Regeneration Process

Step 1: Update Your Schema

Edit your schema files in the workspace to add fields, modify types, change relationships, or add new entities.

Step 2: Trigger Regeneration

Execute regeneration through the SDK API with your server configuration and schema location.

Step 3: What Gets Updated

Regenerated (overwritten each time):

• Generated resolvers (existing custom implementations are preserved through the generation process)
• GraphQL model structures
• GraphQL runtime code
• Application interfaces, infrastructure repositories, and controllers
• Default resolver schemas
• Mock files

Preserved (never overwritten):

• Custom resolver implementations
• Custom model extensions
• Custom repository code
• Server shutdown functions
• Custom infrastructure code
• Test files

Important Notes

• Always use regeneration for existing projects
• Custom resolvers are preserved automatically
• The workspace location is used to read schemas
• Temporary files are cleaned up after generation

---

Validating Schemas

Before generating or regenerating, validate your schemas to catch errors early.

Using Schema Validation

Trigger validation through the SDK API by providing the location of your schema files.

Two-Phase Validation

Phase 1 — Semantic Validation:

• Directive syntax correctness
• Type references resolve to defined types
• Constraint types are valid
• Relationship parameters are correct

Phase 2 — Pragmatic Validation:

• Every table type has a primary key
• Foreign key references exist and are correct
• Relationship mappings are valid
• Constraint expressions are syntactically valid
• No circular references in relationships

Validation Response

Success: Returns confirmation that the schema is valid

Failure: Returns detailed error messages describing what needs to be fixed, including type-specific issues, missing constraints, invalid references, and syntax errors

Best Practice

Always validate before generation:

1. Update schema files
2. Run validation
3. Fix any errors
4. Run regeneration or creation

---

Deleting Objects

Remove types from your schema using a migration configuration that specifies what to drop.

What Happens

The system reads your migration configuration, places it in the server directory, and triggers regeneration which processes the migration to remove the specified entities.

Migration Configuration

Describe what to remove by specifying types to drop entirely or fields to remove from existing types.

---

Testing Custom Logic

Create a temporary test server for validating custom logic before deploying changes.

What Happens

The system creates a new test server, copies base code, generates resolvers from your schema, processes custom operations, runs code generation, creates configuration, and optionally starts the server for testing.

---

Working with Custom Resolvers

Adding Custom Operations

Step 1: Create Custom Schema

Define custom operations in a custom schema file, marking them with the appropriate custom directive.

Step 2: Regenerate

Run regeneration. The system creates stub files for new operations while skipping existing implementations.

Step 3: Implement

Edit the generated stub files to replace placeholder implementations with your business logic.

Step 4: Test

Use GraphQL Playground to test your custom operations with sample queries.

Step 5: Re-Regenerate (Safe)

When you add more custom operations, regeneration preserves existing implementations and creates stubs only for new operations.

See Custom Resolvers for detailed implementation patterns.

---

The Workspace Concept

The DDK uses a workspace as a bidirectional staging area between your files and the generated server. Understanding this flow is critical for advanced usage.

Workspace Structure

The workspace mirrors the server structure but only contains user-modifiable files including custom service interfaces, domain logic, custom controllers, custom model extensions, custom resolvers, custom infrastructure code, and test files.

Bidirectional Migration

During regeneration, the workspace is migrated twice:

1. Workspace to Server (before generation):

Custom resolver files and custom code are copied to the server to preserve your implementations during the generation process.

2. Server to Workspace (after generation):

Generated models, mocks, new resolvers, and migration configuration are copied back to the workspace for your continued development.

First-Time Workspace

If the workspace doesn't exist yet, it's created from the workspace boilerplate template.

---

Testing Your Server

Starting the Server

Using Docker Compose

Navigate to your generated server directory and start all services including PostgreSQL database, Redis (if configured), and the GraphQL server.

Using Make

Use the provided makefile to run the server.

Manual Start

Run the server directly using the Go runtime.

Accessing GraphQL Playground

Once the server is running, the GraphQL playground is accessible at the server's root path, allowing you to explore the schema and test queries.

Testing CRUD Operations

Test creating, reading, updating, and deleting entities using the GraphQL playground. The generated API supports standard CRUD operations with field selection, filtering, pagination, and sorting.

Testing Relationships

Query related entities through the relationship fields defined in your schema. The generated resolvers handle loading related data automatically.

Authentication

If JWT authentication is enabled, set the Authorization header with a Bearer token to access protected operations.

---

Deployment

Docker Deployment

The generated Docker Compose configuration is ready for deployment with pre-configured services for PostgreSQL, Redis (if enabled), and the GraphQL server.

Environment Variables

The generated server reads configuration from environment variables including database connection details, server port, Redis URL, authentication keys, logging configuration, and auto-migration settings.

Production Considerations

1. Disable auto-migration — Use manual migrations in production
2. Use Managed Databases — Leverage cloud-managed database services
3. Use Managed Redis — Leverage cloud-managed cache services
4. Container Orchestration — Deploy on Kubernetes or similar platforms
5. Load Balancing — Use standard load balancing solutions
6. Secret Management — Use secure secrets management services
7. Monitoring — The generated server uses structured logging compatible with standard logging aggregation systems

Database Migrations

The generated server includes migration configuration for managing schema changes in production. For production deployments, use migration tools rather than auto-migration to have full control over database schema evolution.

---

Common Workflows

Workflow 1: New Project from Scratch

1. Design your schema
2. Validate schema
3. Create server with schema
4. Test generated CRUD API
5. Deploy using Docker

Workflow 2: Adding Fields to Existing Types

1. Update schema with new fields
2. Validate schema
3. Regenerate server
4. Test new fields
5. Deploy update (auto-migration handles columns if enabled)

Workflow 3: Adding Custom Business Logic

1. Create custom schema with custom operations
2. Regenerate server
3. Implement custom resolver stubs
4. Test custom operations
5. Deploy

Workflow 4: Adding Relationships

1. Update schema with relationship mappings
2. Validate schema
3. Regenerate server
4. Test relationship queries
5. Deploy

Workflow 5: Removing Types or Fields

1. Use deletion configuration with migration specification
2. Or remove from schema and regenerate
3. Create migration for production if auto-migration doesn't handle drops
4. Test remaining functionality
5. Deploy

Workflow 6: Iterative Development

The typical development loop involves editing the schema, validating, regenerating, testing, implementing custom logic, regenerating again, testing, and deploying. Custom implementations are always preserved across regenerations.

---

Configuration Reference

Server Creation Parameters

Parameter	Type	Required	Description
Server name	string	Yes	Name of the server
Server port	number	Yes	HTTP port
Server path	string	Yes	Parent directory for generated server
Database schema	string	Yes	PostgreSQL schema name
Database name	string	Yes	Database name
Database host	string	Yes	Database host
Database user	string	Yes	Database username
Database password	string	Yes	Database password
Database port	number	Yes	Database port
Redis URL	string	No	Redis connection string
JWT enabled	boolean	No	Enable JWT middleware
Auto-migrate	boolean	No	Enable auto-migration
Log level	string	No	Logging level
Service name	string	No	Service identifier

Regeneration Parameters

Parameter	Type	Required	Description
Server name	string	Yes	Name of the server
Server path	string	Yes	Path to server parent directory
Schema path	string	Yes	Path to workspace

Validation Parameters

Parameter	Type	Required	Description
Location of files	string	Yes	Path to schema directory

---

Troubleshooting

Generation Failures

Issue: Schema validation errors
Solution: Run validation first and fix all reported errors. Check for missing primary keys, invalid constraints, and unresolved type references.

Issue: Generator not found
Solution: The generator configuration must point to the correct generator location.

Issue: Code generation failures
Solution: Ensure the server directory has valid dependencies and all configuration is present and correct.

Issue: File permission errors
Solution: Check write permissions for the server path.

Runtime Errors

Issue: Database connection failed
Solution: Verify PostgreSQL is running and credentials match configuration.

Issue: Redis connection failed
Solution: Check Redis URL or disable Redis if not needed.

Issue: Port already in use
Solution: Change server port in configuration or stop the conflicting service.

Issue: Transaction errors in resolvers
Solution: Ensure you're getting the transaction from context properly in custom resolvers.

Regeneration Issues

Issue: Custom resolvers not preserved
Solution: Ensure custom resolver files follow the proper naming convention and are in the correct directory.

Issue: Schema changes not reflected
Solution: Verify the schema path points to the workspace root.

Issue: Stale generated code
Solution: Check all generation logs to ensure all generation steps completed successfully.

---

Related Documentation

• Schema Guide - Writing schemas with directives
• Custom Resolvers - Adding custom business logic
• Architecture - How the DDK works internally
• Examples - Real-world examples
• FAQs - Common questions