← nyxcore-systems
7 min read

From Protocol to Production: Launching the IPCHA API & Dashboard

We just hit a major milestone, deploying our IPCHA protocol modules as a full-fledged, rentable API service complete with a user dashboard. Dive into the architectural decisions, the challenges we overcame, and what's next for this intelligent arbitration system.

IPCHAAPIFastAPINext.jsTypeScriptDockerPrismaBackendFrontendDeploymentLessons LearnedDevelopment

Every ambitious project has its pivotal moments – those sprints where weeks of foundational work coalesce into something tangible and user-facing. For us, that moment just arrived. We're thrilled to announce a significant leap forward: the deployment of the full IPCHA protocol as a rentable API service, complete with an integrated dashboard for managing access and monitoring usage.

This hasn't been a small feat. Our goal was clear: take the 15 intricate modules of the IPCHA protocol – a system designed for intelligent, decentralized arbitration – and wrap them in a robust, scalable, and user-friendly API. Today, we've successfully deployed it all to production, running smoothly across four interconnected containers.

Let's pull back the curtain and explore the journey from a complex protocol to a production-ready service.

The Foundation: Building the IPCHA Protocol

Before we could even think about an API, we had to build the core. This first phase involved a deep dive into the IPCHA specifications, translating them into executable code. We implemented all 15 modules covering everything from scoring and sanitization to arbitration, sycophancy detection, and routing. With 78 passing Python tests ensuring correctness across these critical functions, we laid a rock-solid foundation. This core protocol, committed as b34b44f on main, has been the bedrock for everything that followed.

Bringing IPCHA to Life: The API & Dashboard

The most recent sprint focused on transforming that powerful protocol into a consumable service. This involved a multi-faceted approach, touching every layer of our stack:

1. The IPCHA Sidecar: Our Intelligent Core

At the heart of our new service is a FastAPI sidecar (ipcha/api.py). This Python service acts as the direct interface to the IPCHA protocol, exposing 10 critical endpoints: health, score, score/opposition, sanitize, validate, arbitrate, route, sycophancy/metrics, audit/rejections, and evaluate. By running it as a dedicated sidecar, we keep our core application lightweight and ensure the IPCHA logic is encapsulated and scalable.

2. Orchestration with Docker

Seamless deployment was paramount. We configured our Docker environment (ipcha/Dockerfile + docker-compose.production.yml) to run the IPCHA service on an internal network. Crucially, we added health checks and ensured our main application depends_on the IPCHA sidecar, guaranteeing proper startup order and service availability. Our production environment now boasts four containers: postgres, redis, ipcha (our new sidecar), and app.

3. Data Persistence & Access Control

To support a rentable API, we needed robust database models for tracking usage and managing access. We extended our Prisma schema with three new models: IpchaApiToken, IpchaUsageLog, and IpchaJob. We leveraged Prisma's powerful features like @db.Uuid for unique identifiers, @@map for clean database naming, and defined reverse relations for easy data navigation. Crucially, Row-Level Security (RLS) policies were put in place to ensure data isolation and security for multi-tenant usage.

A dedicated token service (src/server/services/ipcha-token-service.ts) was built to handle nyx_ip_ prefix tokens. This service manages token creation, SHA-256 hashing for secure storage, validation, revocation, and listing – the backbone of our API access control.

4. Seamless Integration: From Internal Client to External Proxy

Our main application needed a clean way to communicate with the IPCHA sidecar. We developed a sidecar client (src/server/services/ipcha-client.ts) with a callIpcha<T>() utility, complete with IpchaClientError handling for robust communication.

For external consumption, we built a comprehensive REST middleware (src/app/api/v1/ipcha/middleware.ts). This middleware is responsible for authentication, rate limiting (burst and daily quotas), scope checking, and usage metering – all essential features for a commercial API. All IPCHA protocol endpoints are exposed via a REST proxy (src/app/api/v1/ipcha/_proxy.ts and 11 route files), handling both synchronous and asynchronous operations.

5. User Experience: The Dashboard

No rentable API is complete without a dashboard! We extended our tRPC router (src/server/trpc/routers/ipcha.ts) to serve both customer-facing data (usage, results, tokens, playground, jobs) and administrative functions (system health, rejections, job management, token control, revocation).

This powers our new dashboard (src/app/(dashboard)/dashboard/ipcha/), featuring 8 distinct tab components: usage, tokens, results, playground, admin-health, admin-audit, admin-jobs, and admin-tokens. Users can now generate tokens, monitor their usage, explore results, and even interact with the IPCHA protocol directly in the playground. Administrators have a full suite of tools to oversee the system.

The entire stack is type-check clean, builds successfully, and all sidecar endpoints have been smoke-tested, confirming their readiness.

Navigating the Rapids: Lessons Learned & Challenges

No development sprint is without its hurdles. Here are some key challenges we faced and the solutions we implemented, offering valuable lessons for future endeavors:

1. Docker Build Context and .dockerignore

  • Challenge: During the Docker build process, we needed specific test files (tests/evaluation/) for the IPCHA sidecar to function correctly, but our .dockerignore file was broadly excluding the tests directory.
  • Lesson Learned: Be precise with .dockerignore. Broad exclusions can inadvertently remove necessary files.
  • Solution: We added an exception to .dockerignore: !tests/evaluation to explicitly include the required directory while keeping other test files out.

2. TypeScript's Strictness with Prisma JSON

  • Challenge: When trying to store arbitrary JSON data in a Prisma Json field, using Record<string, unknown> for the input type led to TypeScript error TS2322. Prisma's InputJsonValue type is stricter, requiring specific primitive types or arrays/objects composed of them.
  • Lesson Learned: Prisma's Json type expects a specific structure. Direct casting from Record<string, unknown> isn't always compatible.
  • Solution: We used JSON.parse(JSON.stringify(body)) to ensure the incoming object was fully serialized and then deserialized into a structure that Prisma's InputJsonValue could accept, effectively converting it to a Prisma-compatible JSON.

3. TypeScript Type Narrowing with Error Handling

  • Challenge: In our systemHealth endpoint, we attempted to catch errors from callIpcha() and return a default value like ({ total: 0 }). This created a union type that TypeScript struggled to narrow, preventing the dashboard UI from accessing specific fields (e.g., sycophancy metrics).
  • Lesson Learned: When providing default values in error handlers, ensure the default type is compatible with the expected success type, or handle narrowing explicitly.
  • Solution: We extracted the default metrics to a const defaultMetrics object with the correct type. Then, we used callIpcha<typeof defaultMetrics>() to enforce the expected return type and chained .then(r => r.total) for specific field access, allowing TypeScript to correctly narrow the types.

4. Environment Variable Management in Docker Compose

  • Challenge: We initially tried to pass OPENAI_API_KEY directly to the ipcha Docker service in docker-compose.production.yml, assuming it would pick up from .env.production. However, it resulted in a warning about a blank string because the variable wasn't explicitly linked to the service's environment.
  • Lesson Learned: Docker Compose services don't automatically inherit all host environment variables unless explicitly told to, or if env_file is specified.
  • Solution: We added IPCHA_SIDECAR_URL=http://ipcha:8100 to .env.production for internal communication. For the OPENAI_API_KEY, which is only needed for the /validate endpoint and not at startup, we decided to add it later via env_file for the ipcha service.

What's Next on the Horizon

With the core API and dashboard now live, we're focusing on polishing and enhancing the experience:

  1. OpenAI API Key for Validation: We'll add OPENAI_API_KEY to .env.production to enable the /validate endpoint in production.
  2. Merge to Main: The feat/cli-api branch will soon be merged into main after final review and testing.
  3. Dashboard UI Testing: Comprehensive testing of the dashboard UI at the production URL, especially /dashboard/ipcha.
  4. External API Testing: Create the first IPCHA API token via the dashboard and conduct external REST API tests.
  5. Refine Docker Compose: Add env_file: .env.production to the ipcha service in docker-compose for cleaner environment variable management.
  6. Robust RLS Policies: Update RLS SQL to use CREATE POLICY IF NOT EXISTS or DROP POLICY IF EXISTS before CREATE POLICY to prevent errors on re-runs.
  7. API Documentation: Consider adding a dedicated API documentation page (e.g., Swagger/OpenAPI) at /api/v1/ipcha/docs for developers.

This milestone marks a significant step towards bringing intelligent, decentralized arbitration to a wider audience. We're excited about the possibilities this opens up and look forward to seeing how developers integrate the IPCHA API into their own innovative projects!