Home / Engine / Chart and Pipeline Engine
Updated Jun 03, 2026 · Affirmology_BackendArchitecture_v1.md
Prepared for Jeff Parker
Status Living document. Pairs with Affirmology_AgentArchitecture_v1.md (the "why") and Affirmology_AutomatedPipelineSpec_v1.md (the original eight-component blueprint). This doc is the working map of where the system is today, where you want it in twelve months, and the open questions that need decisions.
Date June 3, 2026
The system is real. Not a prototype, not a demo. It computes verified charts, generates personalized scripts, renders speech, mixes music, ships an MP3 plus a Sacred Audio Report PDF, all from one CLI command. Six demos have been rendered to date (Jeff, Laura, Steven, Soledad, Colin, Alex), each with both client-facing deliverables and a complete backend audit trail.
What you have right now lives at /Users/jeffreyparker/CLAUDE/AFFIRMOLOGY/affirmology-agent/ and breaks into five working layers.
Layer 1: Deterministic chart engines. Four pure-function calculators that turn birth data into structured chart facts. Astrology uses Swiss Ephemeris (Moshier, no data files needed). Human Design computes the 88-degree Design offset and maps the Rave Mandala. Gene Keys derives from the same gate activations. Numerology is direct math. These engines share one input contract and produce one merged Chart object that every downstream agent consumes. They have 29 passing pytest tests verifying against Jeff's, Josh's, and Soledad's known charts.
Layer 2: Generative agents. Five Claude-powered agents that take the verified chart and write things from it. script_generator.py writes the spoken affirmation script using the v5 Josh Parini pattern as the canonical reference. verifier.py regex-checks the script against the chart JSON to catch hallucinated placements. audio_synthesis.py calls ElevenLabs to render voice from the cleaned script. audio_mix.py programmatically mixes voice and music with FFmpeg using a voice-anchored timing rule so any voice length lands cleanly under any music bed. sacred_audio_report.py calls Claude (Haiku, for speed) to produce the structured content for the client PDF, then renders HTML via WeasyPrint.
Layer 3: The orchestrator CLI. cli.py is the single entry point. One command takes a person's birth data, runs the chart engines, writes facts files, optionally runs script generation, optionally renders audio, optionally emits the Sacred Audio Report PDF, with auto-tuned ElevenLabs speed so voice always undershoots the music bed. The CLI enforces the new folder layout: client-facing files at the per-person folder's root, everything else in a backend/ subfolder.
Layer 4: Output and audit. Each render produces a deterministic set of artifacts. Client folder root has the final MP3 and the Sacred Audio Report PDF. The backend/ subfolder contains the chart JSON, four pillar facts files, the script markdown, the cleaned voice MP3, the audio render report in markdown, the same report as structured JSON (so a web handler can consume it programmatically), the raw HTML the PDF was rendered from, and the JSON payload Claude returned. This is the receipts layer. Anyone auditing the system can reconstruct every claim.
Layer 5: Tooling and scripts. Helper scripts in affirmology-agent/scripts/ for one-off operations: gen_sacred_audio_report.py retrofits PDFs onto existing renders, gen_one_report.py chunks the four-engine orchestrator into single-engine calls, electional_scan.py walks the ephemeris for date-range queries (used today for the LLC filing report). These exist because the sandbox can only hold one Claude call per shell invocation, but they generalize as a pattern: anything heavy gets a standalone CLI wrapper.
What this means in plain terms: you can hand the agent any person's birth data and walk away with a finished audio plus PDF in about three minutes of compute, for about sixty cents in API costs. The four-engine accuracy bar holds across six different charts. The voice-anchored mix solved the 39-second tail. The auto-tuned speed solved the "rendering at fixed speed always either overshoots or undershoots" problem. The PDF agent produces the methodology document you wanted. The folder restructure separates client deliverables from backend audit.
That is what is built and working.
To talk about where this goes, it helps to step out of file paths and into a four-tier model. Each tier has a clear job. Adding new agents means putting them in the right tier and respecting the contracts between tiers.
Tier 1, the Knowledge Layer. Everything the system knows, separated from anything the system computes. Right now this is small: the Gene Keys gate-to-frequency table, the Rave Mandala gate wheel constants, the Pythagorean numerology mapping, the canonical v5 reference script. In future this becomes the proprietary corpus you want to build: chart-element interpretations across astrology, Vedic, Human Design, Gene Keys, numerology, somatic protocols, meditation traditions, EFT. Static data plus periodically refreshed external sources.
Tier 2, the Computation Layer. The deterministic engines that turn inputs into structured truth. Today: chart math. Tomorrow: also script-element analysis, audio quality metrics, A/B test statistics, ephemeris timing computations for electional queries. The rule for this layer is no LLM. If an LLM call lives here, it belongs in Tier 3.
Tier 3, the Generation Layer. The Claude-powered agents that turn structured truth into language and structured output. Today: script generator, prose report generator, Sacred Audio Report content. Tomorrow: many more specialists, each with a tight job description and a small system prompt, all reading from the same Chart JSON contract.
Tier 4, the Production Layer. The deliverable assembly. Voice synthesis, mixing, video rendering (future), PDF generation, web form ingestion, payment, email, delivery. Anything that touches an external service or produces a customer-facing artifact.
A new agent is well-architected when it sits in exactly one tier and respects the contracts to the tiers above and below. A new agent is poorly architected when it mixes layers, especially when it tries to compute and generate in the same call.
In twelve months, the system you want is recognizable from where it stands today, but with three things added that change its character. The first is breadth. You add many more agents, each narrow, each verifiable. The second is depth. You add the proprietary knowledge corpus that lets the system stop searching the web in real time. The third is self-improvement. You add agents that watch the other agents and tune them.
Let me walk through what each looks like.
Your current generation tier has five agents. The mature version probably has twenty to thirty. Each one is small, focused, and replaceable. Here is what I would propose adding, organized by what each agent's single job actually is.
Knowledge corpus builders. One agent per knowledge tradition, each running on a schedule (nightly or weekly), each crawling public-domain or fair-use sources, each writing structured records into the Tier 1 knowledge store. A Gene Keys corpus builder pulls from sources independent of Richard Rudd's copyrighted writing (classical I Ching translations, public-domain hexagram interpretations, academic papers on the King Wen sequence). A Human Design corpus builder works the freely available portions of Ra Uru Hu's lectures and community-licensed transcripts. A Western astrology agent pulls from public-domain classical sources (Lilly, Bonatti, Ptolemy translations) plus modern Creative-Commons astrology blogs. A Vedic astrology agent pulls from public-domain Sanskrit text translations. A numerology agent works the Pythagorean and Chaldean public-domain bases. A somatic-protocols agent collects EFT tapping scripts, breathwork protocols, vagus-nerve regulation language, all from open-access public health sources. Each writes provenance with every entry, so the methodology PDFs can cite real sources.
Scriptwriter specialists. Today you have one script generator and one canonical v5 reference. The mature version has several. A meditation-script agent (current). A breathwork-script agent (different cadence, breath cues, fewer affirmation lines). A morning-activation agent (shorter, more energizing). An EFT-tapping agent (paired with somatic tap-point cues). A sankalpa agent (single intention, longer pauses, traditional yoga nidra structure). A visioning agent (longer arc, third-person to first-person transitions, future-pacing). Each draws from the same chart and the same knowledge corpus but produces a different artifact for a different use case.
Audio specialists. Today: synthesis plus mix. Mature version adds an audio QC agent that scans renders for the mid-track volume dropouts you saw at speed 1.16-plus (probably an ElevenLabs Turbo regime artifact). A music curator that manages the bed library, tags by mood and tempo, picks the closest match per script profile. A multi-provider router that picks between ElevenLabs and Fish Audio and any future provider based on cost, language, voice availability, and quality. A loudness normalizer that targets industry-standard LUFS so every demo sounds the same volume.
Editorial guardians. A style-lint agent that reads any generated script and flags clichés, em dashes, corporate-therapy vocabulary, second-person violations, all the rules in your prompts. A voice consistency agent that compares new content against your canonical brand voice and flags drift. A chart-claim verifier (you have one for scripts already; expand it to PDFs and any future video transcripts).
Operations agents. A cost-watchdog agent that tracks ElevenLabs credits, Anthropic spend, and storage costs, and alerts when approaching limits or projects monthly overruns. An ephemeris drift detector that periodically re-runs known fixtures against the current chart engines to catch silent regressions. A render archive agent that indexes every shipped MP3 and PDF, makes them searchable, computes time-to-deliver and cost-per-render statistics.
The agent that builds agents. This is the self-improvement piece you raised. Once you have logs of every generation (which you already do, in backend/), an agent can read across many renders, look for patterns ("scripts shorter than 850 words rate higher in user-feedback once you have feedback;" "Charlotte at speed 1.10 to 1.13 produces fewer dropouts than 1.14+"), and propose changes to the prompts of other agents. This is real but expensive to do well. Worth scoping conservatively: one improvement candidate per week, reviewed by a human (you) before it ships.
The breadth above describes new generation agents. They are useless without a knowledge corpus to draw from. Right now your generation agents work entirely from the chart JSON plus whatever Claude already learned at training time. That has two problems. Claude's training-time knowledge is unverifiable, may be wrong on niche traditions, and is mid-2024-stale. And every render that needs current information requires a real-time web search, which is slow and inconsistent.
The corpus solves both. You build, over weeks or months, a structured database where each record contains: a chart element (a gate, a sign-house combination, a Gene Key, a Vedic nakshatra, a life path number, a tapping point, a meditation technique), a set of interpretive lines drawn from real sources, provenance citations for each line, license status (public domain, Creative Commons, fair use, proprietary), and a verification status (peer-reviewed by you, by a trusted advisor, or auto-derived).
Once the corpus exists, generation agents stop reasoning from raw Claude knowledge and start composing from corpus records. Latency drops because no more real-time web searches. Accuracy goes up because every interpretive claim has a source. Cost drops because Haiku can compose from retrieved records as well as Sonnet can reason from scratch, often better. And ownership becomes meaningful: this corpus is yours, and over time becomes the defensible asset that a competitor cannot replicate without doing the same months of work.
The corpus is also where Sol, Colin, and other future contributors plug in. They submit corpus entries (their own interpretive language, their own protocols, their own clinical insights for EFT or somatic work) through a structured submission interface. The corpus grows with the team.
Practically, this becomes a Postgres database (Supabase is the path of least resistance) with tables like chart_element, interpretation, source, protocol, voice_template. Each generation agent gets a retrieval helper that pulls the relevant rows by chart element. The corpus has versioning so old renders can be re-traced to the corpus state at the time.
You mentioned this twice. It is the loop where the system gets better over time without you having to manually tune it. Three parts.
Production telemetry. Every render emits structured logs: which prompts, which model versions, which speed, which voice, which corpus revision, how long, how much money. You already have most of this in audio_report.json. Standardize and centralize.
Outcome capture. Once the web form is live and people are using the audios, you capture which audios get listened to all the way through, which get re-listened, which get shared, which get refunded, which lead to a follow-on purchase. This requires user accounts and analytics. Add it after the form is up.
The improver agent. Reads telemetry plus outcomes weekly. Proposes specific changes: "Audios over seven minutes drop listener completion by 18 percent. Consider tightening the script generator's word target from 900 to 820." "Charlotte voice retains listeners 12 percent better than Sarah for Virgo Sun users. Consider biasing voice selection by Sun sign." You read the proposals and approve or reject. Approved changes go to a staging branch, get tested against a sample of historical renders, and if they hold up, ship.
This loop is the difference between a one-time product and a perpetually-improving product. It is also the hardest piece to build correctly. Worth scoping carefully and starting small.
Six items that should be on the architecture map even if they were not in your message.
Voice rights and consent. If breathwork coaches or members pay to clone their own voice for personalized journeys, you need a signed consent flow, voice-print storage policy, retention rules, and a deletion path. Most jurisdictions treat voice prints as biometric data, with different rules than text or audio recordings. Get this clean before the first paid voice clone happens.
Birth data is personal data. The web form collects date and time and place of birth. In some jurisdictions that is sensitive. You need a privacy policy, a data-retention default, a one-click user-deletion flow, and a clear statement of what you do and do not store. Especially relevant if you eventually go to market in the EU or Brazil. Cheap to do right at the start, expensive to retrofit.
Multilingual delivery for Miami. Miami is a Spanish-and-Portuguese-speaking market in significant part. The script generator can be prompted in Spanish today. Charlotte does not speak Spanish convincingly. ElevenLabs Multilingual v2 does. Fish Audio supports thirty-plus languages. Plan for a bilingual launch from day one. It is the single biggest differentiator from competitors who default to English-only.
A/B testing as a first-class feature. Once you have multiple voices, multiple script lengths, multiple music beds, multiple visual treatments, you need to know which combinations convert and retain. Build the experiment framework before you have many experiments to run. Saves rebuilding later.
Affiliate or partner economics. Your breathwork-coach membership tier is interesting. Concretely it requires: license tracking per coach, attribution from coach-event signups back to Affirmology, revenue split if monetized, brand-asset packaging, reporting dashboards. Doable but not trivial. Worth a dedicated agent and a separate database.
Historical time-zone hell. Birth in Boston in 1976 has DST history that modern geocoding APIs sometimes get wrong. You already saw a chart with a slightly degraded Ascendant for Soledad. Build a historical TZ correction layer using the IANA tz database with tzdata historical data. Quick to add now, painful to debug for individual users later.
You asked about home laptop today, Mac mini next, cloud eventually. Here is the realistic path.
Now through the Miami launch. Stay on your laptop for development. Add a Mac mini as the "always on" production box: same Python code, runs continuously, exposes a local network endpoint. You can hit it from your phone or laptop. You can SSH into it from anywhere via Tailscale or similar. This is where overnight knowledge-corpus builders run. This is where the agent that builds agents runs its weekly review. This is where scheduled renders for paying users go in the post-launch period.
The Mac mini hosts: the Python code, the Postgres database (Supabase if you want managed, or a local Postgres if you want everything in your office), the music bed library, the historical render archive, and the agent processes. It does not host the web form. The web form lives separately.
At launch and after. The web form is a Vercel-deployed Next.js application. It collects birth data, validates it, and sends a request to your Mac mini's secure endpoint. The Mac mini renders the audio and PDF. The Vercel app receives the deliverable URLs and presents them to the user. This split keeps the public-facing site simple and globally fast, while the heavy compute lives on hardware you own.
Twelve months out. The Mac mini gets too small. You containerize the Python code into Docker, deploy to Fly.io or Railway, and the architecture stays identical. The same code that ran on your laptop runs in the cloud. The only thing that changes is where the process lives and who pays for the CPU. This is the architectural rule from your original Affirmology_AgentArchitecture_v1.md and it still holds.
Open Claude (Claude Code) on the Mac mini. You mentioned cloud desktop access. This is good and worth doing. Install Claude Code on the Mac mini. Access it from any device via Tailscale or a remote desktop solution. Your conversations with Claude can run anywhere, and the code, knowledge corpus, and render outputs stay in one place.
You floated this and it deserves explicit architecture. Here is how I would frame it.
A "Practitioner Tier" subscription gives a breathwork coach, EFT practitioner, or men's-work facilitator a web interface where they can configure a journey template. They pick a script type (meditation, breathwork, EFT, sankalpa, visioning), set their event title and date, optionally upload a custom intro by them, and generate a batch of personalized audios for their attendees in advance. Each attendee submits birth data via a coach-branded form, gets a personalized audio rendered against the coach's template choices, and receives delivery on the day of the event.
Important architectural notes. The coach's template is stored as a structured JourneyTemplate record that the script-generator agent consumes alongside the chart JSON. The branding is light: the audio voice and music are Affirmology's; the coach's brand appears in the PDF, the email, and a brief audio intro. Every attendee enters your email funnel with explicit opt-in. The coach earns affiliate credit on any attendee who later subscribes to a direct Affirmology product.
The mechanism that makes this work cleanly: the same agents that produce single-user renders today produce template-driven batch renders for partners. The chart engines do not care whether the user came in through the public form or a coach's form. The script generator picks a different prompt template based on JourneyTemplate.kind. The delivery layer sends to a branded email or a branded landing page. One pipeline, two go-to-market motions.
These are the decisions that should shape priorities. I do not want to assume.
The first batch of questions is about scope and timeline.
The second batch is about the team.
The third batch is about product direction.
A concrete sequence that gets the highest-value pieces in place before you go into deeper teaching and Miami prep.
Week one. Stand up the web intake form on Vercel. Wire it to call the existing CLI on your laptop (or a Mac mini if you set one up). One person submits, one audio plus PDF gets delivered to their email. End-to-end working. The existing JSON sidecar I built into the audio report is exactly what the web handler reads to know where the files are.
Week two. Stand up Supabase Postgres. Migrate the per-render JSON sidecar into a render table. Add a user table with email and opt-in status. Add a corpus_entry table even if empty. Get the schema in place before there are many records to migrate.
Week three. Build the first knowledge-corpus agent. Pick one tradition. I would suggest classical Western astrology because the public-domain source material is enormous and well-organized. The agent runs nightly on your Mac mini, ingests ten to fifty new entries per night, writes them to corpus_entry with provenance. Within a month you have hundreds of verified records that the script generator can start drawing from.
Week four. Wire the audio QC agent. It scans every new render for the mid-track dropouts you saw on Sol and Alex, flags any render that exceeds 3 dB volume variance in a sliding window, surfaces them for human review. This is the first agent that watches the other agents, and it sets the pattern for the broader self-improvement loop.
That is one month of work that gets you a live web form, a database, the start of a proprietary corpus, and the first quality-control automation. Each piece compounds. By month three the corpus is meaningful, by month six it is defensible, by month twelve it is the asset that makes Affirmology not-just-another-AI-audio-product.
End of document. Annotate, push back, ask me anything. The next version of this is whatever shape your answers to Part Seven give it.