← nyxcore-systems
7 min read

Orchestrating Worlds: Building nyxBook, Our Multi-Agent Story Engine

We just hit a massive milestone: launching nyxBook, a sophisticated multi-agent system designed to orchestrate the entire book creation process. Dive into the architectural decisions, the features we built, and the invaluable lessons learned along the way.

nyxCoremulti-agentAIstorytellingfullstackTypeScriptPrismatRPCReactworkflow-engine

At nyxCore, our ambition has always been to push the boundaries of what's possible with intelligent agents. Today, I'm thrilled to share a major leap forward: the completion of nyxBook. This isn't just a feature; it's a full-fledged multi-agent book orchestration system, designed to empower authors and creators by managing everything from high-level plot beats to nuanced character voices.

In a recent intensive development sprint, we tackled the monumental task of bringing nyxBook to life. The goal was clear: implement the entire system, covering schema design, backend services, extending our workflow engine, building a robust tRPC API, crafting an intuitive dashboard UI, and integrating it seamlessly into our existing platform. I'm proud to report: mission accomplished. The codebase is type-check and lint clean, poised for its first real content import.

Let's break down how we built this beast.

The Foundation: Database & Data Models

Every powerful application starts with a solid data model. For nyxBook, we introduced four new Prisma models to prisma/schema.prisma, forming the structural backbone of our storytelling engine:

  • Book: The central entity, holding all metadata for a given literary project.
  • BookChapter: Individual chapters, linked back to their Book.
  • BookCharacter: Detailed character profiles, essential for consistent voice and behavior.
  • BookBeat: Plot beats or story moments, allowing for high-level narrative planning.

Crucially, we also extended existing models to support nyxBook's multi-agent capabilities. Persona.scope now allows us to define agents as "global" or "book"-specific, ensuring that our literary agents only appear where they're needed. Similarly, Workflow.bookId creates a direct relationship, allowing workflows to be explicitly tied to a particular book project.

The Brain: Backend Services & Workflow Extensions

The real magic happens in the backend, where our agents come alive. We developed a suite of services to handle the complex logic of book creation:

  • src/server/services/nyxbook-import.ts: This service handles the ingestion of external content. It features a sophisticated dual-layer parsing system, distinguishing between the core narrative content and what we call "Aktenlage" – background information, internal notes, or meta-data associated with a chapter, crucial for informing our agents without burdening the narrative itself.
  • src/server/services/nyxbook-context.ts: To make our agent prompts dynamic and context-aware, this service provides template variable resolution for {{book.*}} fields. Imagine agents automatically knowing the book's genre, target audience, or current plot points.
  • src/server/services/nyxbook-voice.ts: Character consistency is paramount. This service generates CORS-formatted character voice prompts, ensuring agents adopt the correct tone, lexicon, and style. What's more, it supports "level-based evolution," meaning characters can develop and adapt their voice as the story progresses and they gain "experience."
  • src/server/services/workflow-engine.ts: Our core workflow engine received a significant upgrade. We added bookContext to the ChainContext and introduced four powerful new template variables: {{book.worldRules}}, {{book.characters}}, {{book.beats}}, and {{book.character.HANDLE}}. These additions allow agents to access a rich, dynamic understanding of the book's world, its inhabitants, and its narrative progression, enabling truly intelligent interactions.

The API: tRPC & Seamless Integration

Our backend powers a robust API built with tRPC, ensuring end-to-end type safety and an excellent developer experience.

  • src/server/trpc/routers/nyxbook.ts: This new router provides full CRUD operations for books, chapters, characters, and beats. But the exciting part lies in its generation mutations:
    • generateChapter
    • generateAktenlage
    • runVoiceTest (for characters)
    • runDialecticalReview (for narrative critique)
    • A pipelineStatus query to monitor ongoing agent activities.
  • We registered nyxBookRouter in our main src/server/trpc/router.ts and added a scope filter to src/server/trpc/routers/personas.ts, allowing us to fetch "global", "book", or "all" personas as needed.

The Interface: A Dashboard for Storytelling

A powerful backend needs an equally powerful frontend. We integrated nyxBook deeply into our dashboard experience:

  • Dashboard & Sidebar: nyxbook process types now appear in the active processes list with distinctive amber icons/colors, making it easy to track agent activity. A dedicated nyxBook sidebar entry (with a BookOpen icon in the Knowledge group) provides quick access.
  • src/app/(dashboard)/dashboard/nyxbook/page.tsx: This is the central hub for book management, featuring a comprehensive 5-tab layout:
    • Overview: High-level book details.
    • Chapters: A list of all chapters.
    • Beat Board: A visual representation of plot beats.
    • Characters: Character bible and management.
    • Workshop: Where the magic of generation happens.
    • This page utilizes our InPageSidebar pattern for enhanced navigation.
  • Custom UI Components: We developed several specialized components to visualize and interact with book data:
    • book-pipeline.tsx: A horizontal 5-stage visualization with elegant SVG connectors, showing the progression of a book through its various phases.
    • chapter-flow.tsx: Per-chapter step indicators, giving a clear view of where each chapter stands in its development.
    • beat-board.tsx: A grid layout for beats, color-coded by status for at-a-glance project health.
    • character-card.tsx: Detailed character bible entries, an XP bar to visualize their development, and a quick voice test button.
  • src/app/(dashboard)/dashboard/nyxbook/[bookId]/chapters/[num]/page.tsx: This dedicated chapter editor allows authors to refine the narrative, Aktenlage, and add notes, all with a convenient save mutation.

Finally, to kickstart our multi-agent literary team, we added six book-scoped literary personas and the nyxBook Literary Team itself to our prisma/seed.ts data.

Challenges Encountered & Lessons Learned

No complex development sprint is without its hurdles. These moments, however, often yield the most valuable lessons:

  1. React Query v5's onSuccess Removal:

    • Tried: Using the onSuccess callback directly in tRPC v11's React Query v5 useQuery() hook to update local state after data fetch.
    • Failed: Received TS2769: 'onSuccess' does not exist in type 'UseTRPCQueryOptions'. React Query v5 famously removed onSuccess from useQuery options, moving it to useMutation or recommending useEffect for useQuery side effects.
    • Workaround: We adapted by replacing onSuccess with a useEffect hook that watches for changes in chapter.data to populate our editor state.
    • Lesson: Always be aware of breaking changes in major library versions. For useQuery in React Query v5 (and by extension tRPC v11), data-loaded side effects should be handled by watching the data property within a useEffect hook, not onSuccess.

  2. Missing UI Component:

    • Tried: Importing Textarea from @/components/ui/textarea for a consistent UI.
    • Failed: TS2307: Cannot find module '@/components/ui/textarea'. The component simply hadn't been created or wasn't in the expected path.
    • Workaround: We reverted to using the native <textarea> HTML element and applied our existing nyx-* CSS utility classes to style it, maintaining a consistent look without blocking progress.
    • Lesson: While component libraries are great for consistency, sometimes a quick native fallback is necessary. It also highlighted a small gap in our component library that we'll address.

What's Next? The Road Ahead

With the core nyxBook system in place, our immediate next steps are all about validation and bringing content to life:

  1. Seed the Database: Run npm run db:seed to populate our database with the book personas and the nyxBook Literary Team.
  2. Test Import: Use the new nyxBook UI's "Import" button to ingest content from our inselWerk source path.
  3. Verify Chapter Editor: Navigate to an imported chapter, edit its narrative and Aktenlage, and confirm the save mutation works as expected.
  4. Test Generation: From the Workshop tab, initiate a "Generate Chapter" workflow and verify that a new workflow is correctly created and executed by our agents.
  5. End-to-End Persona Scoping: Crucially, we'll test that book-specific personas do not appear in global workflow or discussion selectors, ensuring proper isolation and context.

This marks a significant milestone for nyxCore. nyxBook isn't just a tool; it's a vision for collaborative, intelligent storytelling. We're incredibly excited about the possibilities it unlocks and look forward to sharing more as we continue to refine and expand its capabilities.

json
{
  "thingsDone": [
    "Full multi-agent book orchestration system (nyxBook) implemented",
    "4 new Prisma models for book entities",
    "Persona and Workflow models extended for book scoping",
    "Backend services for filesystem import, context resolution, and character voice generation",
    "Workflow engine extended with book-specific context and template variables",
    "Full CRUD + 4 generation mutations implemented in tRPC router",
    "Comprehensive dashboard UI with 5-tab layout and custom components",
    "Chapter editor for narrative, Aktenlage, and notes",
    "Book-scoped literary personas and team seeded"
  ],
  "pains": [
    "React Query v5 'onSuccess' removal required 'useEffect' workaround",
    "Missing UI component ('textarea') required native HTML fallback"
  ],
  "successes": [
    "All 10 tasks completed",
    "Typecheck and lint clean codebase",
    "Robust multi-agent system foundation laid",
    "Seamless integration into existing nyxCore dashboard",
    "Dynamic and context-aware agent interactions enabled"
  ],
  "techStack": [
    "TypeScript",
    "Next.js",
    "React",
    "tRPC",
    "Prisma",
    "PostgreSQL",
    "TailwindCSS"
  ]
}