Specs

Technical reference for ATXbbs v0.1. Last updated 2026-04-19.

Architecture

visitor / browser
       │
       ▼ HTTPS
┌──────────────────────────────────────────────────────────┐
│ nginx 80/443                                             │
│   /             → static HTML (homepage, etc.)           │
│   /bbs/         → static HTML (conference + thread pgs)  │
│   /bbs/live/*   → reverse proxy to gunicorn :8920        │
└──────────────────────────────────────────────────────────┘
       │                              │
       ▼ static files                 ▼ proxy
  /var/www/                      ┌────────────────────────┐
  └ austinspring.com/            │ gunicorn (1 worker, 4  │
    ├ index.html                 │ threads) :8920         │
    ├ bbs/                       │   ↓                    │
    │ ├ <conf>/                  │ Flask app              │
    │ │ ├ index.html             │   ↓                    │
    │ │ └ <thread_num>/index.html│ SQLite (single .db)    │
    │ └ live/    (Flask routes)  └────────────────────────┘
    │
    └ archive caches (raw Wayback HTML)
      ├ archive/threads/<conf>/<num>.html
      └ archive/conferences-union/<conf>.html

Stack

Layer	Component	Notes
Language	Python 3.12	Standard CPython, no compiled deps
Web framework	Flask 3	Vanilla; no Flask-WTF / Flask-Login extensions
Templates	Jinja2	9 templates total. Static archive pages are pre-rendered, not Jinja.
WSGI	gunicorn 22	1 worker, 4 threads, max-requests=200
Reverse proxy	nginx	SSL via certbot/Let's Encrypt
Database	SQLite	Single file at /opt/springbbs/spring.db
Email	Resend HTTPS API	SMTP blocked by hosting (DigitalOcean); Resend's HTTPS endpoint works
Inbound mail	ForwardEmail.net	Catch-all forward to a real Gmail inbox
Backup	Backblaze B2 + rclone	Nightly sync + dated 30-day snapshots
OS	Ubuntu 24.04 LTS	Single $6/mo droplet, 1 vCPU, 1GB RAM

Data model

users (
  id INTEGER PRIMARY KEY,
  username TEXT UNIQUE NOT NULL,
  password_hash TEXT NOT NULL,
  bio TEXT,
  email TEXT,                       -- optional, for password reset + reply notifs
  notify_replies INTEGER DEFAULT 1, -- per-user opt-out
  is_admin INTEGER DEFAULT 0,
  joined_at TEXT,
  last_seen TEXT
)

threads (
  id INTEGER PRIMARY KEY,
  conf TEXT NOT NULL,               -- conference slug, e.g. "drool"
  author_id INTEGER REFERENCES users,
  title TEXT NOT NULL,
  created_at TEXT,
  updated_at TEXT,                  -- bumped on new reply
  post_count INTEGER DEFAULT 0,
  pinned INTEGER DEFAULT 0,         -- 1 = sticky on conf index
  deleted_at TEXT,                  -- soft-delete (null = visible)
  deleted_reason TEXT
)

posts (
  id INTEGER PRIMARY KEY,
  thread_id INTEGER REFERENCES threads,
  author_id INTEGER REFERENCES users,
  body TEXT NOT NULL,
  created_at TEXT,
  deleted_at TEXT,
  deleted_reason TEXT
)

archive_comments (   -- comments on RECONSTRUCTED archived threads
  id INTEGER PRIMARY KEY,
  conf TEXT NOT NULL,
  thread_num INTEGER NOT NULL,      -- the original yapp topic number
  author_id INTEGER REFERENCES users,
  body TEXT,
  created_at TEXT,
  deleted_at TEXT,
  deleted_reason TEXT
)

password_reset_tokens (token, user_id, email, created_at, used_at)
notification_tokens   (token, user_id, created_at)              -- for unsubscribe links
read_log              (user_id, conf, thread_num, last_read_at) -- for unread-since-last-visit (planned)
conference_meta       (slug, welcome_html, host_user_id, updated_at)

URL conventions

Path	What
/	Site homepage
/bbs/	Conference list (static hub)
/bbs/<conf>/	Conference index (static, pre-rendered)
/bbs/<conf>/<num>/	Archived thread (static)
/bbs/live/c/<conf>/	Conference index (Flask, includes live threads)
/bbs/live/c/<conf>/<tid>/	Live thread (Flask)
/bbs/live/c/<conf>/new	Start new topic (Flask, login required)
/bbs/live/archive/<conf>/<num>/	Archived thread + live comments (Flask)
/bbs/live/signup / /login / /welcome	Auth flows
/bbs/live/forgot / /reset/<token>	Password reset
/bbs/live/settings	Profile + email + notification opt-out
/bbs/live/notify/off/<token>	One-click unsubscribe (link in every notif email)
/bbs/live/recent[?n=N]	Activity feed (default 60, max 500 — yapp's pulse)
/bbs/live/members	Member directory
/bbs/live/admin	Admin queue (admin-only)
/bbs/live/stats.json	JSON stats endpoint (homepage live strip)
/bbs/live/rss/<conf|all>.xml	RSS feed
/sitemap.xml / /bbs-sitemap.xml	SEO sitemaps (3,180+ URLs)

Security

• Passwords: werkzeug.security.generate_password_hash (PBKDF2-SHA256 by default).
• CSRF: hand-rolled HMAC of session seed + secret key. Hidden <input name="csrf"> on every POST form, verified server-side.
• Rate limiting: in-memory sliding-window per IP. Defaults: signup 5/hr, login 15/15min, new_thread 10/hr, reply 40/10min, forgot 5/hr, reset 10/hr, settings 30/hr. GETs unrestricted.
• Cookies: SESSION_COOKIE_HTTPONLY=True, SAMESITE=Lax, SECURE=True in production.
• Soft delete: moderation hides content via deleted_at timestamp; data preserved for audit/undo.
• SSL: Let's Encrypt cert auto-renewed by certbot timer.

Performance

• Static archive: 3,700+ thread pages served by nginx directly, no Flask roundtrip. Trivially cacheable by any CDN.
• Flask is only hit for: live conferences, posts/replies, auth, search, RSS, admin. ~5% of traffic.
• SQLite footprint: single file, currently ~120KB. Comfortably handles 100s of concurrent readers and dozens of writers/sec.
• Cold-cache page render: <100ms typical. WAL mode enabled.

Backups + integrity

• Nightly rclone sync of /var/www/austinspring.com/ and /opt/springbbs/ to B2.
• Nightly dated snapshots at b2:walhuswholetech-snapshots/austinspring-YYYY-MM-DD/, last 30 days kept.
• Daily integrity check emails sysop via Resend if drift detected (live thread count vs cache, homepage size, Flask responding).
• Homepage rollback guard — locked .GOOD copy; cron sentinel restores within 2 min if live drops below locked size.
• STATE.yaml manifest auto-regenerated nightly with current counts, critical-file MD5s, cron jobs.

Reconstruction pipeline (Wayback → site)

1. CDX scan — query Wayback CDX API for all /yapp-bin/public/read/<conf>/<num> URLs ever captured.
2. Per-thread fetch — for each (conf, num), fetch the LATEST capture using the id_ Wayback prefix (raw content, no toolbar).
3. Cache — write to archive/threads/<conf>/<num>.html.
4. Conference index synthesis — for confs without a usable Wayback browse-page, regenerate index from cache by parsing each thread's <H3> + author + response count.
5. Static render — build-thread-pages.py --all walks the cache, parses yapp HTML with regex (1990s markup is too wild for lxml), outputs modern-styled static HTML to /var/www/austinspring.com/bbs/.
6. Cross-link — auto-inject banners between thematic conferences and their reference sites (austen ↔ austen.com, drool ↔ firth network).
7. OG / Schema.org — inject <meta property="og:..."> + JSON-LD DiscussionForumPosting on every rendered thread.
8. Sitemap regen — per-conference sitemaps + sitemap index.

What ATXbbs is NOT

• Not a Discord/Slack alternative — message-per-second isn't the model. Topics + responses, hours-to-days cadence.
• Not a Discourse competitor — no enterprise SSO, no plugins ecosystem, no email-as-first-class. Single sysop, single droplet, simple stack.
• Not "no-email" by accident — yapp required email but no verification; we require email + verify-to-post (read free, post verified). Email is required at signup. Verification required to post. Reply notifications opt-in.
• Not text-mode (telnet/SSH) — yapp + PicoSpan supported terminal access. Web-only here. The phosphor CSS is the homage.
• Not algorithmic — no "for you" feed. Time-ordered or explicit filters only.

What's NOT yet shipped

See the roadmap. Tier-1 items pending: full-text search across archive + live, "unread since last visit" filter, per-conference hosts tier, topic subscriptions, @mentions, Markdown in posts, mobile-responsive polish.