zig-project

Zig Project Architecture

Core Principles

• No hidden behavior — No hidden allocations, no hidden control flow, no macros
• Explicit allocators — Pass allocator as parameter, never use global allocator
• Comptime over macros — Use comptime for generics and metaprogramming
• Error unions — Use !T for explicit error handling, avoid anyerror
• defer/errdefer — Resource cleanup at scope exit
• No backwards compatibility — Delete, don't deprecate. Change directly
• LiteLLM for LLM APIs — Use LiteLLM proxy for all LLM integrations

---

No Backwards Compatibility

Delete unused code. Change directly. No compatibility layers.

// ❌ BAD: Deprecated function kept around
/// Deprecated: Use newFunction instead
pub fn oldFunction() void {
    @compileLog("oldFunction is deprecated");
    newFunction();
}

// ❌ BAD: Alias for renamed functions
pub const old_name = new_name; // "for backwards compatibility"

// ❌ BAD: Unused parameters
fn process(_: *const Config, data: []const u8) !void {
    _ = data;
}

// ✅ GOOD: Just delete and update all usages
pub fn newFunction() void {
    // ...
}

// ✅ GOOD: Remove unused parameters entirely
fn process(data: []const u8) !void {
    // ...
}

---

LiteLLM for LLM APIs

Use LiteLLM proxy. Don't call provider APIs directly.

const std = @import("std");
const http = std.http;

pub const LLMClient = struct {
    allocator: std.mem.Allocator,
    base_url: []const u8,
    api_key: []const u8,

    pub fn init(allocator: std.mem.Allocator, base_url: []const u8, api_key: []const u8) LLMClient {
        return .{
            .allocator = allocator,
            .base_url = base_url,  // "http://localhost:4000"
            .api_key = api_key,
        };
    }

    pub fn complete(self: *LLMClient, prompt: []const u8, model: []const u8) ![]u8 {
        // Use OpenAI-compatible API through LiteLLM proxy
        var client = http.Client{ .allocator = self.allocator };
        defer client.deinit();

        // Build request to LiteLLM proxy...
        _ = prompt;
        _ = model;
        return "";
    }
};