Preface
Welcome to the Sober Network Handbook.
This document describes the architecture, operation, and philosophy of a system that most people will never see. Beneath every city-specific recovery resource website in our network — beneath the facility directories, the blog articles, the chatbot conversations, the search results that connect someone in crisis to a bed that could save their life — there is an autonomous intelligence system running continuously, learning from its own decisions, and getting measurably smarter every day.
This handbook exists because we believe in building in public. The recovery industry is opaque by default. We chose transparency. Every architectural decision documented here is a real decision running in production. Every system described is alive and operational. We are not describing what we plan to build. We are describing what is already built, already running, already learning.
This is a living document. As the system evolves, so will this handbook. What you read today will be expanded, revised, and deepened over time — just like the system it describes.
Intended Audience
This handbook is written for two audiences simultaneously.
The first audience is technical — engineers, developers, architects, and anyone who has ever wondered what happens when you give autonomous agents a shared communication layer and let them run unsupervised. If you have read documentation for systems like FreeBSD, Kubernetes, or distributed systems research papers, you will feel at home here. The architecture is documented with enough depth that a competent engineer could understand every layer.
The second audience is strategic — operators, investors, and anyone interested in how artificial intelligence can be applied to real-world problems at scale. This handbook demonstrates something specific: an AI system that doesn't just answer questions, but operates a business. It monitors, analyzes, recommends, learns from outcomes, and improves its own decision-making over time. The strategic reader will find the compounding intelligence thesis and trajectory analysis particularly relevant.
Both audiences will find something unexpected: a system built not by a team of dozens, but through the methodical application of autonomous agents coordinated by a single operator. This is what happens when AI is treated not as a feature, but as infrastructure.
Our Mission
The Sober Network operates on a principle of radical transparency. We believe AI systems that affect human lives should be understood, not hidden. We publish this documentation not because we are required to, but because the world needs to see what autonomous AI systems are actually capable of — and why they are necessary.
Addiction does not wait for business hours. It does not pause while a webmaster updates a directory. It does not care whether a treatment facility's phone number is current or whether the nearest detox center is still accepting patients. People in crisis need information that is accurate, comprehensive, and available at three in the morning on a Tuesday.
No human team, regardless of size, can monitor a network of city-specific recovery websites across a growing portfolio, continuously auditing content, verifying data, optimizing search visibility, tracking engagement, managing outreach, and responding to real-time changes — all while learning from the outcomes of every action taken. The scale of the problem demands automation. But automation without intelligence is just scheduled failure.
This is why Sam exists. This is why the swarm exists. This is why the learning layer exists. Not because AI is trendy, but because the problem we are solving requires autonomous intelligence to solve well. Every site we bring online, every facility we verify, every person we connect to care — that is the mission. The technology documented in this handbook is how we execute it.
Organization of This Handbook
This handbook is divided into seven parts.
Part I, Getting Started introduces the Sober Network, its technical foundation, and the scope of the operation. Readers unfamiliar with web infrastructure will find the LAMP Stack chapter in Part VI useful as supplementary reading.
Part II, The Swarm describes the multi-agent architecture that powers autonomous operations. This is the system's most distinctive feature — eight specialized agents communicating through a shared event bus, producing coordinated behavior that no single agent was programmed to exhibit.
Part III, Sam — The Intelligence documents the decision layer. Sam reads the output of every agent, scores every city, detects anomalies, and generates prioritized recommendations. Sam cannot execute — a deliberate architectural constraint explained in detail.
Part IV, The Learning Layer covers the most consequential subsystem: how Sam learns from its own recommendations, adjusts its internal weights, and accumulates institutional knowledge that compounds over time.
Part V, Operations describes the daily autonomous cycle and the monitoring systems that keep everything running without human intervention.
Part VI, The Technology provides deep technical context: the LAMP stack, language models, image generation, and the retrieval-augmented knowledge base that powers the AI chatbot.
Part VII, The Vision presents the compounding intelligence thesis and the long-term trajectory of a system that gets smarter every day.
Chapter 1Introduction
1.1. Synopsis
This chapter provides an overview of the Sober Network — what it is, what it does, and why it exists. After reading this chapter, you will understand the scope of the system, the problem it solves, and the principles that guide its design.
1.2. Welcome to the Sober Network
The Sober Network is a portfolio of city-specific addiction recovery resource websites. Each site serves a single metropolitan area — Los Angeles, Houston, Miami, Denver, Phoenix, Boston, and a growing list of others — providing comprehensive directories of treatment facilities, original editorial content, resource guides, and an AI-powered chatbot that helps visitors navigate their options in real time.
Beneath the public-facing websites is an autonomous infrastructure that most visitors will never see: a swarm of specialized AI agents, a central intelligence layer called Sam, an event-driven communication bus, and a self-improving learning system that measures the outcome of every action and adjusts accordingly.
This documentation describes that infrastructure.
1.3. About the Project
The Sober Network was not designed by committee. It was built iteratively by a single operator who recognized that the addiction recovery information landscape was fragmented, unreliable, and poorly served by existing technology. The solution was not to build a bigger website. It was to build an intelligent system capable of operating a growing network of websites autonomously.
The project follows three guiding principles:
Autonomy over headcount. Rather than hiring a team to manage each city site individually, the system was designed so that a single operator, augmented by AI agents, could manage an arbitrarily large portfolio. The agents do the work. The orchestrator enforces safety. Sam provides intelligence. The human provides direction.
Learning over guessing. Every recommendation the system makes is tracked. Every outcome is measured. The system does not rely on assumptions about what works — it discovers what works empirically, through a continuous feedback loop that adjusts its own priorities based on real-world results.
Transparency over secrecy. This handbook is proof of that principle. We document our systems publicly because we believe the future of AI is comprehensible AI. If a system is too complex to explain, it is too complex to trust.
1.4. A Living System
The system described in this handbook is not static. It runs continuously. Agents execute tasks around the clock. Sam generates a briefing every morning. The learning layer captures a snapshot of the network's state every day. Weights shift. Insights accumulate. The system you read about today is measurably different from the system that was running six months ago — not because someone rewrote it, but because it learned.
Chapter 2The Foundation
2.1. Synopsis
This chapter describes the technical foundation on which the entire system operates: the server infrastructure, the software stack, and the domain architecture that allows the network to scale.
2.2. The Server
The entire Sober Network — every website, every agent, every database, every cron job, every API endpoint — runs on a single cloud server. This is a deliberate architectural choice, not a limitation. Consolidation reduces latency between components, simplifies deployment, and creates a single point of observability. The server is monitored continuously by the InfraAgent and the Watchdog.
The server runs a standard Linux distribution with a LAMP stack (Linux, Apache, MySQL, PHP). This is the same proven foundation that runs a significant portion of the internet. It was chosen for reliability, extensive documentation, and the ability to move fast with a small team.
2.3. The LAMP Stack
For readers unfamiliar with web infrastructure, Chapter 16 provides a deep dive into each component of the LAMP stack — what it does, why it was chosen, and how the Sober Network uses it.
Linux is the operating system. It manages hardware resources, runs processes, and provides the environment everything else executes in. Apache is the web server. When someone visits losangelessober.com, Apache receives the request and routes it to the correct application. MySQL is the database. Every facility record, every agent communication, every learning snapshot is stored in MySQL tables. PHP is the programming language. Every agent, the orchestrator, Sam's decision layer, and the learning system are written in PHP.
The stack is augmented with several additional services: a local language model server for AI inference, a caching layer for performance, and automated backup systems for data protection. But the foundation is LAMP — the same stack that has powered mission-critical web applications for decades.
2.4. Domain Architecture
Each city in the network has its own domain: losangelessober.com, houstonsober.com, miamisober.com, and so on. All domains resolve to the same server. Apache uses virtual host configuration to route each domain to the correct site directory.
All sites share a unified template system. The visual design, the page structure, the JavaScript, the CSS — everything lives in a shared directory. Individual cities do not have their own copies of the template. When the template is updated, every site in the network reflects the change immediately. This is how a single operator can manage a growing portfolio without the maintenance burden scaling linearly with the number of cities.
Each city has its own database tables, dynamically resolved at runtime using a city prefix derived from the domain. There are no hardcoded city lists anywhere in the codebase. The domain registry — the list of which domains exist and which cities they serve — is the single source of truth. Every agent, every cron job, and every scoring function reads from it dynamically.
Chapter 3The Network
3.1. Synopsis
This chapter describes what each city site provides to visitors, the data model underlying the facility directories, and how the network scales horizontally.
3.2. What Each Site Provides
Every city site in the network offers four primary resources:
Facility directories — searchable, categorized listings of treatment facilities including sober living homes, detox centers, treatment programs, and support group meetings. Each listing can include contact information, insurance acceptance, photos, reviews, and detailed descriptions.
Editorial content — blog articles targeting high-intent search queries related to addiction recovery in that city. Articles are generated using AI language models, reviewed, and optimized for search visibility. Content serves both an informational purpose (helping visitors understand their options) and an organic traffic purpose (attracting visitors through search engines).
The AI chatbot — a conversational interface powered by a retrieval-augmented generation (RAG) system built on a knowledge base of thousands of recovery-related documents. The chatbot can answer questions about treatment options, insurance, what to expect, and how to find help. See Chapter 19 for technical details on the knowledge base.
Resource guides — curated information pages covering topics like intervention planning, insurance navigation, and family support.
3.3. The Facility Data Model
Each city maintains four database tables, distinguished by a city prefix and a category suffix: sober living (SL), detox (DX), treatment (TR), and meetings (AA). The schema is standardized across all cities. A facility record includes the facility name, address, coordinates, contact details, website, description, photo references, insurance information, and metadata used for scoring and display.
The facility database is the core data asset of the entire network. Every other system — content generation, outreach, revenue tracking, and Sam's city scoring — depends on the quality and completeness of this data. The FacilityAgent is dedicated entirely to maintaining and enriching it.
3.4. Horizontal Scaling
Adding a new city to the network is a deployment operation, not a development project. The domain is registered, the virtual host is configured, the database tables are created with the standard schema, and the unified template automatically serves the new site. No code is modified. No templates are duplicated. The new city immediately inherits every feature, every agent capability, and every operational process that every other city has.
Sam begins scoring the new city in its next analysis cycle. Agents begin auditing it. The learning layer starts tracking it. From the moment of deployment, the new city is a full participant in the autonomous system. This is how a network grows from a handful of cities to dozens without proportional increases in operational complexity.
Chapter 4Swarm Intelligence
4.1. Synopsis
This chapter introduces the most distinctive architectural feature of the Sober Network: the agent swarm. After reading this chapter, you will understand what swarm intelligence is, why it was chosen over traditional monolithic architectures, and how emergent behavior arises from simple agents following simple rules.
4.2. What Is a Swarm?
In nature, swarm intelligence emerges when simple organisms — ants, bees, termites, birds in a murmuration — follow local rules and produce global behavior that no individual organism planned or understands. An ant does not know the colony's strategy. It follows pheromone trails, responds to nearby ants, and carries food when it finds it. The colony's complex behavior — building structures, farming fungus, waging war, optimizing supply routes — emerges from millions of these simple, local interactions.
The Sober Network's agent system is a computational swarm. Eight specialized agents operate independently, each following its own narrow set of rules. No agent knows what the other agents are doing. No agent has a picture of the whole system. They communicate exclusively through a shared messaging layer — the event bus — publishing observations and responding to events.
The coordinated behavior of the system — a new facility being added, triggering content generation, triggering sitemap updates, triggering search engine notification, triggering outreach scheduling — was never programmed as a single workflow. It emerges from the interaction of independent agents through the event bus. This is the defining characteristic of swarm architecture: the whole is greater than the sum of its parts.
For background on swarm intelligence theory, see Beni & Wang's foundational 1989 paper on robotic swarms, or Bonabeau, Dorigo, and Theraulaz's Swarm Intelligence: From Natural to Artificial Systems (Oxford University Press). The principles described in those works are directly applicable to what is documented here.
4.3. The Biology of Coordination
Consider how the system handles a new facility discovery. The FacilityAgent scrapes a public source and finds a treatment center not yet in the database. It inserts the record and publishes an event: facility.added. The FacilityAgent's job is done. It has no idea what happens next.
The event bus routes facility.added to the ContentAgent, which sees the event and generates a blog article about recovery resources in that city, incorporating the new facility. ContentAgent publishes content.generated.
The event bus routes content.generated to the SEOAgent, which regenerates the sitemap and submits it to search engines. SEOAgent publishes sitemap.updated.
Meanwhile, the original facility.added event was also routed to the OutreachAgent, which queues an outreach email to the facility offering a featured listing.
Four agents. Four independent actions. One coordinated workflow. No agent called another agent. No orchestrator dictated the sequence. The behavior emerged from simple rules: "when I see an event I care about, do my job and publish what I did."
4.4. Emergent Behavior
Emergence is the phenomenon where complex system-level behavior arises from simple component-level rules. In the Sober Network swarm, emergence manifests in several ways:
Self-healing. When the InfraAgent detects a site returning errors, it publishes an alert. The event bus routes this to the Watchdog, which checks for stalled processes and attempts automatic remediation. If a service needs restarting, the Watchdog handles it. No human intervened. The system healed itself because independent components reacted to a shared signal.
Priority cascades. When AnalyticsAgent reports a traffic spike in a particular city, Sam's scoring algorithm ranks that city higher. This leads to more content generation recommendations for that city, which leads to more SEO audits, which leads to more outreach. A single observation — traffic is up — cascades into a coordinated multi-agent response without anyone directing it.
Adaptive resource allocation. Sam's city scoring, informed by the learning layer's evolving weights, naturally directs agent activity toward the cities with the highest growth potential. Over time, as the weights adjust based on real outcomes, the swarm's collective behavior shifts to match what is actually working rather than what was assumed to work.
4.5. Why Swarm Architecture?
The alternative to a swarm is a monolith — a single program that does everything in sequence. Monoliths are simpler to build but catastrophically fragile at scale. If the SEO function fails, it takes down content generation. If the outreach module has a bug, it blocks analytics. Everything is coupled. Everything breaks together.
The swarm architecture provides three critical properties:
Fault isolation. If the ContentAgent crashes, the SEOAgent, FacilityAgent, OutreachAgent, and every other agent continue operating normally. The failed agent's events queue up in the event bus and are processed when it recovers. No cascading failures. No system-wide outages from a single component bug.
Complete audit trail. Every agent interaction, every event published, every event consumed, every inter-agent message is logged with timestamps, payloads, and results. When something unexpected happens, the event log provides a complete forensic record of what every agent did and why. This is not a debugging convenience — it is an operational necessity for a system that runs autonomously.
Composability. Adding a new agent to the swarm requires zero modification to existing agents. The new agent subscribes to events it cares about, publishes events for its outputs, and immediately participates in the swarm's emergent behavior. The system's capabilities grow without refactoring.
Chapter 5The Agents
5.1. Synopsis
This chapter describes each agent in the swarm: its domain of expertise, its capabilities, and its role in the collective behavior of the system.
5.2. Agent Model
Each agent is a self-contained PHP class with a narrow domain of expertise. Agents accept a city parameter dynamically, perform their specialized task, and return structured results. They share no state. They call no other agents. They communicate exclusively through the event bus.
InfraAgent
SEOAgent
ContentAgent
FacilityAgent
AnalyticsAgent
OutreachAgent
RevenueAgent
DesignAgent
5.3. InfraAgent
The InfraAgent is the swarm's eyes on the physical layer. It pings every site in the network and reports status codes and response times. It monitors server load, disk usage, memory pressure, and process health. It triggers automated backups and flushes caches when performance degrades. When hardware-level problems occur, InfraAgent is the first to publish an alert through the event bus — triggering the Watchdog's remediation protocols.
5.4. SEOAgent
The SEOAgent performs technical audits of every site: meta titles, descriptions, canonical tags, schema markup, sitemaps, robots configuration. It identifies issues and attempts automated repairs. The weekly audit scans every city in the network dynamically. When content-level problems are found, the agent publishes events that route to ContentAgent. SEO and content are tightly coupled through the event bus but never directly connected — a textbook example of swarm coordination.
5.5. ContentAgent
The ContentAgent generates SEO-optimized articles using language models, targeting high-intent recovery search queries. It audits existing content for gaps — cities with no blog, cities with thin content, topics that are trending but uncovered. Content generation is one of the highest-impact actions in the system, and Sam's learning layer tracks content recommendations more carefully than almost any other category because the feedback signal is clear: did organic traffic increase?
5.6. FacilityAgent
The FacilityAgent manages the core data asset: treatment facilities. It inserts new facilities, scrapes public sources for discoveries, and enriches existing records with photos, reviews, contact information, and insurance details. When a new facility is added, it triggers a chain reaction through the event bus — demonstrating the swarm's emergent coordination at its most visible.
5.7. AnalyticsAgent
The AnalyticsAgent connects to the analytics platform and retrieves traffic data across all properties: users, pageviews, top pages, traffic sources, city-level breakdowns. This data is Sam's primary input — it feeds city scoring, trend detection, content prioritization, and anomaly detection. Analytics data flows into every daily snapshot and becomes part of Sam's long-term memory.
5.8. OutreachAgent
The OutreachAgent manages email campaigns to treatment facilities, promoting featured placement on the network. It tracks send volumes, open rates, responses, and errors. Outreach connects to a broader revenue pipeline: discovery, pre-listing, cold outreach, follow-up sequences, lead scoring, and conversion tracking — forming a complete funnel from facility identification to monetization.
5.9. RevenueAgent
The RevenueAgent tracks the monetization layer. How many facilities are claimed versus unclaimed. Current recurring revenue. Potential revenue if all listings were converted. Lead capture rates across the network. Sam uses this data to identify the highest-leverage opportunities: cities with high traffic but no revenue represent the biggest gaps between current and potential.
5.10. DesignAgent
The DesignAgent handles template deployment. Because every site shares the unified template system, a single deploy updates the entire network instantly. Design changes are the least frequent operation, but when they happen, they propagate everywhere simultaneously.
Chapter 6The Event Bus
6.1. Synopsis
The event bus is the nervous system of the swarm. This chapter describes the publish-subscribe model, event lifecycle, chain reactions, and the communication log that creates a complete audit trail.
6.2. Publish-Subscribe Model
The event bus implements a simple but powerful pattern: publish-subscribe (pub-sub). Any agent can publish an event — a typed message with a payload, priority, and optional target. Events are stored in a persistent queue. A dispatcher process runs on a fixed interval, reads pending events, routes them to the appropriate handler, executes the handler, and records the result.
Agents do not know who will consume their events. Publishers are decoupled from subscribers. This decoupling is what enables the swarm's composability — a new agent can subscribe to existing event types without modifying any other component.
6.3. Event Lifecycle
Every event passes through a defined set of states:
| State | Description |
|---|---|
pending | Event published, awaiting dispatch |
processing | Dispatcher has claimed the event and is executing the handler |
completed | Handler executed successfully, result recorded |
failed | Handler threw an error; event will retry up to a configurable limit |
expired | Event exceeded its time-to-live without being processed |
6.4. Chain Reactions
Event handlers can publish new events, creating multi-step automated workflows. A single triggering event can cascade through the system, coordinating the actions of multiple agents without any agent knowing about the others. Chain depth is capped to prevent infinite loops. Agents cannot publish events that target themselves. See Chapter 4, Section 4.3 for a detailed example of a chain reaction in action.
6.5. The Communication Log
Every inter-agent message is logged: sender, receiver, event reference, message summary, timestamp. This creates a complete communication history that Sam reads during analysis to understand agent activity patterns. The log is also invaluable for debugging — when something unexpected happens, you can trace the exact sequence of events and inter-agent messages that led to it.
Chapter 7What Sam Is
7.1. Synopsis
This chapter introduces Sam: the intelligence layer that sits above the agent swarm, observing everything, understanding patterns, and recommending actions. Critically, this chapter explains why Sam cannot execute — and why that constraint is the system's most important safety feature.
7.2. Sam's Role
Sam is not a chatbot. Sam is not a script. Sam is the decision layer of the Sober Network — an autonomous intelligence that reads the output of every agent, analyzes the state of the entire network, scores each city by growth potential, detects anomalies, and proposes prioritized actions.
If the agents are the swarm's hands and eyes, Sam is the swarm's brain. But it is a brain with a crucial constraint.
7.3. The Read-Only Constraint
Sam cannot execute. This is the most important design decision in the entire system. It is an architectural boundary, not a policy. The decision layer class has no access to write methods. Sam receives an orchestrator reference but can only call read operations through it.
Sam reads agent outputs, analyzes patterns, detects anomalies, scores cities, and proposes actions. But Sam cannot run a command, modify a file, change a database record, or trigger a workflow. Every recommendation includes a category, action, reasoning, priority, and impact assessment — and then it waits. The orchestrator decides whether and when to execute.
This separation exists because the system manages infrastructure that real people depend on. Addiction recovery is not a domain where you move fast and break things. A bug in an execution engine could take sites offline, publish incorrect facility information, or corrupt data that someone in crisis is depending on. By keeping Sam read-only, the worst case for any Sam bug is a bad recommendation — which the orchestrator's safety rails can filter.
Chapter 8Analysis & Scoring
8.1. Synopsis
This chapter describes Sam's analysis pipeline, the city scoring algorithm, and the anomaly detection system.
8.2. The Analysis Pipeline
When Sam analyzes, it reads from every agent sequentially: infrastructure health, server status, traffic analytics, monetization status, content audit, outreach activity, and lead reporting. The results compose a complete picture of the network at a single point in time. This snapshot becomes the basis for scoring, recommendations, anomaly detection, and briefings.
8.3. City Scoring
Sam ranks every city by growth potential using a weighted formula. The inputs include traffic volume, facility density, content depth, outreach engagement, and revenue capture rate. The weights are not static — they are pulled from the self-adjusting weight table and evolve over time based on which factors actually correlate with growth in the real data.
Early in the system's life, all weights are equal. Sam is guessing about what matters. Over months and years, the weights drift as the feedback loop accumulates evidence. Some factors turn out to be more predictive than initially estimated. Others less. Sam discovers this empirically.
8.4. Anomaly Detection
Sam watches for problems across multiple categories: sites returning error codes, slow response times, disk pressure, high server load, outreach delivery failures, service outages. Each anomaly receives a severity rating and is published to the event bus, where it triggers appropriate responses from the Watchdog and other agents.
Chapter 9Briefings
9.1. Synopsis
Sam generates structured intelligence reports on daily and weekly cycles.
9.2. The Daily Briefing
Every morning, Sam generates a comprehensive briefing: infrastructure status, traffic overview, revenue status, content gaps, outreach activity, lead count, event bus activity, and the learning report — how many snapshots have accumulated, how many insights are active, the recommendation success rate, and which weights have drifted from their defaults. The briefing is the system's consciousness made visible.
9.3. The Weekly Briefing
The weekly briefing goes deeper: full city rankings, complete recommendation list, learning intelligence report with top insights, weight drift analysis, and recommendation outcome history. It provides the strategic view that informs long-term decision-making.
Chapter 10How Sam Learns
10.1. Synopsis
This chapter describes the seven-step learning cycle that executes daily, transforming Sam from a static analyzer into a system that improves its own decision-making over time. This is the subsystem with the highest long-term strategic value.
10.2. The Seven-Step Cycle
Each individual step is small. The compounding is in the repetition. Run this cycle once and nothing meaningful happens. Run it every day for a year and the system's recommendations are measurably more targeted. Run it for four years and you have something no competitor can replicate without investing the same four years.
Chapter 11Memory & Trends
11.1. Synopsis
Before the learning layer, Sam had no memory between runs. This chapter describes how snapshots give Sam long-term memory and how trend detection builds institutional knowledge.
11.2. Snapshots
The snapshot table is Sam's long-term memory. One row per day, every day, for a year. Fast-access numeric columns for the key metrics. A complete JSON blob of the full analysis for deep retrieval. Snapshots enable everything else: trend detection, recommendation evaluation, seasonal pattern discovery, year-over-year comparison. Without memory, there is no learning. Without learning, there is no compounding.
11.3. Trend Detection
The trend detector compares core metrics between today and seven days ago, computing absolute and percentage change for each. Trends exceeding a significance threshold automatically generate or reinforce an insight.
A single observation means nothing. But when Sam sees the same pattern repeatedly — traffic increasing after content generation, leads jumping after facility enrichment, pageviews declining in a particular season — those observations harden into insights with rising confidence scores. This is how Sam builds institutional knowledge: not from assumptions, but from empirical observation accumulated over months and years.
Chapter 12Feedback & Weights
12.1. Synopsis
This chapter describes the feedback loop — the core mechanism that closes the learning cycle — and the self-adjusting weight system that allows Sam to evolve its own priorities.
12.2. The Feedback Loop
When Sam makes a recommendation, the system captures baseline metrics at that moment. After a defined waiting period, Sam compares the current state against that baseline. If the target metric improved, the recommendation is marked successful. If not, failed.
Each recommendation category maps to a specific success metric:
| Category | Success Metric |
|---|---|
| Revenue | Recurring revenue delta |
| Content | Organic pageview delta |
| SEO | User acquisition delta |
| Outreach | Lead capture delta |
| Infrastructure | Uptime delta |
The mapping is explicit and deterministic. There is no ambiguity about what "success" means for any recommendation type.
12.3. Self-Adjusting Weights
Sam maintains ten scoring weights that govern how cities are ranked and how recommendations are prioritized. Each weight starts at a neutral value. Successful recommendations nudge the corresponding weight upward. Failed recommendations nudge it downward. The adjustment scales with impact but is capped per cycle — Sam cannot make wild swings.
These weights are alive. They shift based on what is working and what is not. The values depend on when you look.
Chapter 13Insights & Safety
13.1. Synopsis
This chapter covers the insight engine — how Sam discovers and maintains patterns from data — and the safety rails that prevent the learning system from destabilizing itself.
13.2. The Insight Engine
Insights are patterns Sam discovers empirically. Unlike recommendations (which are action proposals), an insight is an observed truth with a confidence score. Insights come in four types:
| Type | Description | Example |
|---|---|---|
| Trend | Metric direction over time | "Traffic consistently rises after blog publication" |
| Correlation | Action linked to outcome | "Facility enrichment correlates with lead increase" |
| Pattern | Recurring behavior | "Q1 traffic dips annually across all cities" |
| Anomaly | Unexpected deviation | "City X traffic spiked without any agent action" |
An insight starts at moderate confidence when first detected. Each confirming observation increases confidence. Each period without confirmation decays it. Insights below a minimum threshold are deactivated. Only the strongest survive. The total active insight count is capped — when a new insight is generated and the cap is reached, the weakest is pruned.
13.3. Safety Rails
The following constraints are immutable. They are hardcoded in the learning layer and cannot be overridden at runtime. They exist to prevent the system from destabilizing itself.
Weight adjustment cap. No weight can change by more than a bounded amount in any single cycle. Even an extremely positive signal can only shift priorities gradually. Over many cycles, the cumulative shift can be dramatic — but it is always gradual.
Minimum evidence threshold. Insights require a minimum number of confirming observations before they are generated. Sam does not draw conclusions from single data points.
Automatic confidence decay. Insights that are not periodically reinforced by new evidence lose confidence and eventually deactivate. Knowledge has a shelf life unless continuously validated.
Weight floors and ceilings. No weight can drift to zero or infinity. There are hard bounds preventing any single factor from dominating or being eliminated.
Manual lock capability. Any weight can be manually locked to prevent further automatic adjustment. This provides a human override for cases where the operator knows something the data doesn't yet reflect.
Full audit logging. Every weight change, every insight generation, every confidence adjustment is logged with its reasoning. The learning layer is fully transparent and fully traceable.
The philosophy is conservative acceleration. Sam is allowed to get smarter. It is not allowed to get reckless. This is how you build a system you can trust to run unsupervised for years.
Chapter 14The Daily Cycle
14.1. Synopsis
This chapter describes a typical 24-hour operational cycle. The system runs continuously without human intervention.
14.2. The Cycle
Chapter 15The Watchdog
15.1. Synopsis
The watchdog monitors the monitors. It is the system's immune response.
15.2. What the Watchdog Does
The watchdog runs on a tight interval and checks for: stalled processes, orphaned lock files, excessive log growth, orchestrator health, and event dispatcher liveness. If the event dispatcher hasn't run within its expected window, the watchdog raises an alert. If lock files are older than expected job duration, they are cleared to unblock the next execution.
The watchdog detects internal failures and corrects them without waiting for a human. In a system designed to run autonomously, the watchdog is what ensures autonomy doesn't become neglect.
Chapter 16The LAMP Stack
16.1. Synopsis
This chapter is written for readers who want to understand the foundational technology from the ground up. If you are already familiar with web server architecture, you may wish to skip to Chapter 17.
16.2. What LAMP Means
LAMP is an acronym for four open-source technologies that, together, form one of the most proven and widely-deployed web application stacks in history:
L — Linux. The operating system. Linux manages the server's hardware: CPU, memory, disk, network interfaces. It runs processes, manages file permissions, schedules tasks via cron, and provides the environment in which everything else executes. Linux was chosen because it is free, extraordinarily well-documented, runs the majority of the world's servers, and has decades of proven reliability in production environments.
A — Apache. The web server. When someone types losangelessober.com into a browser, that request travels across the internet and arrives at our server. Apache is the software that receives that request, determines which website the visitor wants, and routes the request to the correct application code. Apache handles SSL encryption, virtual host routing (serving different websites from the same server), URL rewriting, and static file delivery. It has been in continuous development since 1995 and currently powers a significant percentage of the world's websites.
M — MySQL. The database. Every piece of persistent data in the system lives in MySQL: facility records, agent communications, event bus messages, learning snapshots, analytics data, user sessions, blog articles, configuration settings. MySQL organizes data into tables with defined schemas, supports complex queries across multiple tables, handles concurrent access from multiple processes, and provides transaction safety to prevent data corruption. The Sober Network's database contains dozens of tables across multiple logical databases.
P — PHP. The programming language. Every agent, the orchestrator, Sam's decision layer, the learning system, the API endpoints, and the website rendering logic are written in PHP. PHP runs on the server side — it executes when a request arrives, generates HTML, and sends the result back to the visitor's browser. PHP was chosen for its deep integration with Apache and MySQL, its extensive standard library, and the speed of development it enables for a small team.
The LAMP stack is sometimes dismissed as "old technology" by those who favor newer frameworks. This dismissal misunderstands the value of maturity. LAMP has been running mission-critical applications for decades. Its failure modes are well-understood. Its documentation is extensive. Its community is enormous. For a system that must run autonomously and reliably for years, maturity is a feature, not a limitation.
Chapter 17AI & Language Models
17.1. Synopsis
This chapter describes how the Sober Network uses artificial intelligence for content generation, analysis, and conversational interfaces.
17.2. Local Language Model
The system runs a local large language model (LLM) server directly on the same infrastructure as the rest of the network. This model handles tasks that require natural language understanding: content generation, facility description enrichment, and chatbot conversation. Running the model locally eliminates per-request API costs and keeps sensitive data on-premises.
17.3. External AI APIs
For tasks requiring the highest capability models — complex content generation, nuanced analysis, strategic reasoning — the system calls external AI APIs. The orchestrator manages API key rotation, rate limiting, and cost tracking. AI API usage is treated as a resource to be budgeted, not an unlimited utility.
17.4. AI in the Agent Swarm
Language models are tools available to agents, not agents themselves. The ContentAgent uses LLMs to generate articles. The FacilityAgent uses LLMs to write facility descriptions from raw data. Sam uses LLMs to generate briefing narratives. But the agents' logic — what to do, when to do it, how to evaluate the result — is deterministic PHP code, not AI inference. This distinction is critical: the system's reliability comes from deterministic orchestration, not from hoping the language model makes good decisions.
Chapter 18Image Generation
18.1. Synopsis
The system uses AI image generation to create visual content for the network.
18.2. How It Works
The image generation pipeline connects to an external AI service capable of creating photorealistic and stylized images from text descriptions. This capability is used for: city-specific hero images, blog article illustrations, facility placeholder images when photos are unavailable, and branded visual content for outreach materials.
Images are generated at multiple resolutions (landscape, portrait, square) depending on the use case and are automatically optimized for web delivery. The system integrates image generation into automated content workflows — when the ContentAgent generates an article, it can request accompanying imagery through the same pipeline.
Chapter 19The Knowledge Base
19.1. Synopsis
This chapter describes the retrieval-augmented generation (RAG) system that powers the AI chatbot.
19.2. What RAG Is
Retrieval-Augmented Generation is a technique that grounds AI responses in a curated knowledge base rather than relying solely on the model's training data. When a visitor asks the chatbot a question, the system first searches the knowledge base for relevant documents, then provides those documents as context to the language model along with the question. The model generates its response informed by specific, verified information rather than general training.
19.3. The Knowledge Base
The Sober Network's RAG knowledge base contains thousands of recovery-related documents covering: treatment modalities, insurance navigation, facility types, intervention strategies, family support resources, medication-assisted treatment, twelve-step programs, harm reduction approaches, and state-specific regulations. This corpus is continuously expanded and updated.
The chatbot can answer questions about treatment options, explain the difference between detox and residential treatment, help visitors understand insurance coverage, and guide someone in crisis toward the most appropriate next step — all grounded in verified information rather than AI hallucination.
For more on RAG architectures, see Lewis et al., "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks" (NeurIPS 2020). The Sober Network's implementation follows the principles described in that paper, adapted for a domain-specific recovery knowledge corpus.
Chapter 20Compounding Intelligence
20.1. Synopsis
This chapter presents the core strategic thesis: why a self-improving system creates a competitive moat that grows wider with time.
20.2. The Thesis
The learning layer's value is not in any single cycle. It is in the accumulation.
Each cycle is a tiny improvement. A weight nudged by a fraction of a percent. An insight confirmed, its confidence rising incrementally. A recommendation pattern validated or invalidated. Day to day, Sam appears the same. But the feedback loop means each improvement makes the next cycle slightly better. Better weights produce better recommendations. Better recommendations produce more successful outcomes. More successful outcomes produce higher-confidence insights. Higher-confidence insights produce even better weights.
This is not a linear process. It compounds.
A competitor can replicate the code. They can copy the architecture. They can build their own agents and their own event bus. What they cannot replicate is the accumulated learning — the insights, the tuned weights, the validated patterns, the feedback history. That dataset only exists because the system ran, day after day, cycle after cycle, accumulating evidence about what actually works. The moat is made of time.
Chapter 21The Trajectory
21.1. Synopsis
This chapter maps the system's evolution from Day 1 to Year 4 and beyond.
21.2. The Timeline
Chapter 22Why This Matters
22.1. Synopsis
This final chapter connects the technical systems described throughout this handbook to the human problem they exist to solve.
22.2. The Problem
In the United States alone, tens of millions of people struggle with substance use disorders. A fraction receive treatment. Among those who seek help, many encounter outdated directories, disconnected phone numbers, inaccurate insurance information, and websites that haven't been updated in years. The information landscape for addiction recovery is fragmented, unreliable, and poorly maintained — precisely at the moment when accuracy matters most.
22.3. The Solution
An autonomous system that never sleeps, never forgets to update a listing, never misses a trend, never stops learning what works. A system that can scale to cover every major city without proportional increases in operational cost. A system that gets better at connecting people to care with every cycle of its learning loop.
That is what this handbook documents. Not a theoretical proposal. A running system. Operational. Learning. Compounding.
22.4. Open Transparency
We publish this handbook because the world needs fewer black boxes and more glass boxes. AI systems that affect human lives should be understood. The architecture should be explainable. The decision-making should be traceable. The learning should be auditable.
This is our contribution to that standard. Read it. Understand it. Hold us accountable to it. And if you are building autonomous systems of your own — consider documenting them just as openly. The future of trustworthy AI depends on it.
Appendix AGlossary
| Term | Definition |
|---|---|
| Agent | A self-contained autonomous program responsible for a single domain of expertise within the swarm. |
| Anomaly | An unexpected deviation from expected system behavior, detected by Sam and classified by severity. |
| Chain Reaction | A multi-step automated workflow where one event triggers a handler that publishes another event, cascading across multiple agents. |
| Confidence Score | A numeric value representing Sam's certainty in an insight, ranging from minimum threshold to maximum, increasing with confirmation and decaying without it. |
| Event Bus | The publish-subscribe messaging system through which all agents communicate. The nervous system of the swarm. |
| Feedback Loop | The mechanism by which Sam evaluates the outcome of its own recommendations by comparing baseline metrics against post-action metrics. |
| Insight | An empirically discovered pattern with a confidence score. Types: trend, correlation, pattern, anomaly. |
| LAMP | Linux, Apache, MySQL, PHP — the foundational web application stack. |
| Orchestrator | The central coordination layer that enforces safety rails, rate limits, and audit logging. The only component authorized to execute actions. |
| RAG | Retrieval-Augmented Generation — a technique that grounds AI responses in a curated knowledge base. |
| Sam | The autonomous intelligence layer that analyzes the network, scores cities, detects anomalies, and generates recommendations. Read-only by design. |
| Snapshot | A complete capture of the network's state at a single point in time. One per day, retained for a year. |
| Swarm | The collective of independent agents whose coordinated behavior emerges from local rules and shared communication, not central control. |
| Weight | A numeric value in Sam's scoring algorithm that determines how much influence a particular factor has on city rankings and recommendation priority. Weights self-adjust based on feedback. |
Appendix BFurther Reading
The following resources provide additional context for the concepts and technologies described in this handbook:
Swarm Intelligence — Bonabeau, Dorigo, Theraulaz. Swarm Intelligence: From Natural to Artificial Systems. Oxford University Press, 1999.
Pub-Sub Architecture — Eugster et al. "The Many Faces of Publish/Subscribe." ACM Computing Surveys, 2003.
Retrieval-Augmented Generation — Lewis et al. "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks." NeurIPS, 2020.
Multi-Agent Systems — Wooldridge. An Introduction to MultiAgent Systems. Wiley, 2009.
Feedback Loops in AI — Sculley et al. "Hidden Technical Debt in Machine Learning Systems." NeurIPS, 2015.
The LAMP Stack — PHP Documentation, Apache HTTP Server Documentation, MySQL Reference Manual.
Small things, done consistently, become extraordinary things given enough time.
This handbook is a living document maintained by the Sober Network project.
For the network itself, visit losangelessober.com.