MEGAMIND SEO Sidecar · feedback and experiment subsystem

Purpose & architecture

Despite its general repository name, this source includes megamind/seo: a Go pipeline for page fetching, schema generation and validation, change detection, queued work, experiment state, learning logs and analytics signals. A Python sidecar and deployment tools form the service boundary. It is a concrete applied subsystem connecting project AI work to website operations.

Scoring formulas and experiment records describe application logic. This audit did not validate live analytics, search ranking gains, deployed schema changes or learned causal effects.

This source generation

This record follows the main branch of Janady13/seo-sidecar at commit c66ba23646cf638023e8803dc201dd69089107c9. The snapshot identifies the source inspected in this audit. It is not a statement about which revision is currently running on a device.

Recovered implementation structure

These paths locate the components and entry points represented by this build. The source register contains their inspected revisions.

• .github/FUNDING.yml
• .github/workflows/publish-pypi.yml
• README.md
• deploy-ga-update.sh
• deploy-sidecar.sh
• megamind/seo/client.go
• megamind/seo/cmd/main.go
• megamind/seo/ga_signal_source.go
• megamind/seo/go.mod
• megamind/seo/schema_canonicalize.go
• megamind/seo/schema_change_detector.go
• megamind/seo/schema_diff_gate.go
• megamind/seo/schema_experiment_engine.go
• megamind/seo/schema_feedback_engine.go
• megamind/seo/schema_generator.go
• megamind/seo/schema_job_queue.go
• megamind/seo/schema_learning_log.go
• megamind/seo/schema_page_classifier.go
• megamind/seo/schema_page_fetcher.go
• megamind/seo/schema_push_client.go
• megamind/seo/schema_site_registry.go
• megamind/seo/schema_state_cache.go
• megamind/seo/schema_throttle.go
• megamind/seo/schema_validator.go
• megamind/seo/schema_worker.go
• megamind/seo/seo_test.go
• megamind/seo/types.go
• megamind_push.py
• pyproject.toml
• requirements.txt
• safe-deploy.sh
• seo_client.go
• sidecar.py

Behavior & verification limits

Scoring formulas and experiment records describe application logic. This audit did not validate live analytics, search ranking gains, deployed schema changes or learned causal effects.

Original project documentation

The following documentation is preserved as a dated source account. Claims in it retain the source’s wording and must be read alongside the implementation notes above.

SEO Sidecar

Inject up-to-date Schema.org JSON-LD into your nginx-served sites with zero crons, zero site file changes, always fresh. A FastAPI sidecar + nginx SSI integration that lets an upstream AI/automation push schemas to your hosting machine in real time.

   

Why this exists

If you host static or server-rendered HTML through nginx and want fresh, dynamic Schema.org JSON-LD in every page's <head> without redeploying the site every time a schema changes, you have three bad options:

1. Edit the HTML files every time → site redeployment per schema change
2. Cron job that rebuilds + redeploys → stale between cron runs, slow propagation
3. Server-side rendering → couples schema generation to your rendering tier

SEO Sidecar is the fourth option. An upstream process (your AI, your CMS, your trend analyzer, whatever) pushes JSON-LD to a tiny FastAPI service on your nginx host. nginx pulls the schema in via SSI on every page load. Schema updates take effect instantly with no site redeployment, no cron lag, no rendering coupling.

Built in production for ThatDevPro's network of nine client websites.

Architecture

<UPSTREAM> (your AI publishing source)
    │
    │  Push over Tailscale (event-driven)
    │  POST /update/{site} with JSON-LD
    │
    ▼
┌──────────────────────────────────────────┐
│ <SIDECAR_HOST> (your nginx host)                │
│                                          │
│  seo-sidecar (localhost:9090)            │
│  ├── SQLite: /var/lib/seo-sidecar/       │
│  ├── Receives pushes from upstream       │
│  ├── Serves schemas to nginx             │
│  └── Keeps history + versioning          │
│                                          │
│  nginx                                   │
│  ├── SSI include on every page load      │
│  ├── Fetches from localhost:9090         │
│  ├── 5min proxy_cache (configurable)     │
│  └── 1s timeout (pages never stall)      │
│                                          │
│  9 hosted sites                          │
│  └── Each gets dynamic JSON-LD in <head> │
└──────────────────────────────────────────┘

How It Works

1. Your upstream service decides a schema needs updating (trend shift, new FAQ, competitor gap)
2. Upstream pushes the new JSON-LD to http://<SIDECAR_HOST>:9090/update/{site} over Tailscale
3. Sidecar stores it in SQLite with version history
4. nginx SSI fetches from localhost:9090/schema/{site} on every HTML page load
5. Schema appears in the <head> of the site — search engines and AI crawlers see it immediately

No cron jobs. No file writes. No site deployments. Upstream controls schema state remotely.

Files

Deploy on the sidecar host

# Copy files to your sidecar host
scp -r seo-sidecar/ <YOUR_SERVER>:/tmp/seo-sidecar/

# SSH in and deploy
ssh <YOUR_SERVER>
cd /tmp/seo-sidecar
sudo bash deploy-sidecar.sh

Then add one line to each nginx server block:

include /etc/nginx/snippets/seo-inject.conf;

Reload nginx:

nginx -t && systemctl reload nginx

Push from your upstream

# Push single site
python megamind_push.py push thatdeveloperguy

# Push all 9 sites
python megamind_push.py push-all

# Bulk push (single HTTP request)
python megamind_push.py push-bulk

# Check what's live
python megamind_push.py status

# View version history
python megamind_push.py history thatdeveloperguy

Or from Go:

client := seo.NewClient("http://<SIDECAR_HOST>:9090", "your-token")
client.Push("thatdeveloperguy", jsonldString)

API Endpoints

Push (MEGAMIND → Sidecar) - POST /update/{site} — Push schema for one site - POST /update-bulk — Push schemas for multiple sites - DELETE /schema/{site} — Remove a schema

Serve (nginx → Sidecar) - GET /schema/{site} — Returns <script type="application/ld+json"> HTML

Monitor - GET /status — All sites, versions, freshness - GET /history/{site} — Version history

Config

Set in /etc/systemd/system/seo-sidecar.service:

Adding New Sites

1. Add the hostname mapping in nginx-seo-sidecar.conf (the map block)
2. Add include /etc/nginx/snippets/seo-inject.conf; to the new site's server block
3. Push a schema: python megamind_push.py push newsite

That's it. No other config changes.

Companion tools

• aio-surfaces — MIT-licensed Python toolkit that generates the four AI-citation surfaces (llms.txt, aeo.json, entity.json, brand.json) from a single site config. Pairs naturally with this — generate schemas with aio-surfaces, push them with this sidecar.
• llms.txt generator — free Hugging Face Space that drafts a spec-compliant llms.txt from any homepage URL.

License

MIT © 2026 Joseph W. Anady (ThatDevPro). See [LICENSE](LICENSE).

Built and used in production by ThatDevPro — SDVOSB-certified veteran-owned web + AI engineering studio. Cassville, Missouri.

Equations in this build

1 linked mathematical records. Each opens its notation, interpretation and source.