Retro Forum

A retro-styled discussion forum application designed to mimic the look and feel of early 2010s bulletin boards while utilizing modern CSS frameworks.

Features

Core Functionality

• User Authentication: Complete registration and login system with session management.
• Thread Management: Users can create new threads, view discussions, and post replies.
• Post Editing & History: Authors can edit posts, with a full version history maintained for transparency.
• AI-Powered Tagging: Threads automatically receive relevant tags generated by Gemini AI.
• AI Moderation: Real-time content analysis using Gemini 2.5 Flash Lite to prevent toxicity and harassment.
• Search: Built-in search functionality to find threads by keywords.
• Custom Error Handling: Fully themed, user-aware error pages for 404 (Not Found), 429 (Rate Limited), and 500 (Internal Server Error) to maintain immersion.
• Real-time Updates: Integrated WebSockets for instant post delivery, notification alerts, and live reaction updates.
• Password Recovery: Secure email-based password reset system using timed tokens.

User Customization

• Profiles: Users can customize their location, occupation, interests, and set an external avatar URL.
• Signatures: Support for text-based signatures that appear below every post.
• Theme Switcher: Users can toggle between three distinct color themes via their profile settings:
  • Default Blue: The classic retro look.
  • Red Alert: A high-contrast red theme.
  • Matrix Green: A terminal-inspired green theme.
  • Dark Mode: This one is a bit easier on the eyes. Theme preferences are persisted using LocalStorage.
• Status Updates: Users can post short status updates to their profiles, visible in the global activity feed.

Social & Interaction

• Reputation System: Users can award reputation points to helpful posts.
• @Mention System: Real-time autocomplete search for usernames when typing @. Mentions are automatically highlighted and linked to user profiles.
• Private Messaging: Secure person-to-person messaging system with an integrated inbox.
• Notifications: System alerts for thread replies, mentions, reputation gains, and new private messages.
• BBCode Support: Rich text formatting including images, YouTube embeds, and custom smilies managed by administrators.
• Rate Limiting: Protection against spam and brute-force attacks via SlowAPI.
• Friend System: Send, accept, or decline friend requests to build a community network.
• Reactions: React to posts with multiple emojis, updated in real-time across all connected clients.
• Shoutbox: A real-time global chat for established members (requires 25+ posts).
• Muting: Users can mute others to hide their content and prevent unwanted interactions.

Bot Personas & Automation

• Deterministic Commands: Interact with system bots via mentions:
  • @SystemBot (System): Provides system telemetry, pings, and technical support links.
  • @SupportBot (Support): Offers navigation help, user profile stats, real-time weather reports (via NWS/wttr.in), and an interactive riddle game with smart hint generation and normalized answer matching.
  • @ArchiveBot (Archive): Fetches latest news, random threads, and performs deep searches using DuckDuckGo integration.
• Admin Bot Console: An administrative interface to trigger AI-generated posts using Gemini 3 Flash Preview, allowing for persona-driven announcements and welcomes.

Administrative Tools

• Dashboard: Overview of site statistics (users, threads, posts, reports).
• Forum Management: Create, delete, and organize forums and subforums.
• Moderation Queue: Review and resolve user-submitted reports.
• Smiley Management: Upload and manage custom BBCode smilies.
• Bot Controls: Reset bot rate limits and manage automated posting cadence.
• Seed Interactions (Optional): To populate the forum with AI-generated users, threads, and realistic conversation trees:

  python seed_interactions.py

  To wipe the seeded accounts and their associated posts:

  python cleanup_seed.py

Tech Stack

• Backend: FastAPI (Python)
• Database: SQLAlchemy (Async) with support for PostgreSQL and SQLite.
• AI Service: Google Gemini API (Generative AI SDK).
• Styling: TailwindCSS (via CDN) + Custom CSS Variables for theming.
• Templating: Jinja2.
• Frontend Logic: Vanilla JavaScript for theme switching and confirmation dialogs.
• Real-time: WebSockets for bi-directional communication.

Project Structure

• templates/
  • layout.html: Base template containing the header, navigation, footer, and theme definitions.
  • index.html: Main forum view listing threads and categories.
  • thread.html: Individual thread view showing posts and the quick reply box.
  • profile.html: User settings page including the theme selector.
  • login.html / register.html: Authentication pages.
  • search.html: Search results display.
  • memberlist.html: Table view of all registered users.

Setup

1. Install Dependencies:

   pip install -r requirements.txt

2. Environment Variables: Create a .env file and configure the following variables:

   • GEMINI_API_KEY: Your Google Gemini API key.
   • DATABASE_URL: Database connection string (defaults to SQLite).
   • SESSION_SECRET_KEY: Secret key for session security.
   • SECRET_KEY: General application secret key used for tokens.
   • SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASSWORD: SMTP configuration for emails.
   • SENDER_EMAIL: The email address used to send system notifications.
   • APP_URL: The base URL of the application (e.g., https://your-forum.railway.app).
   • BOT_MAX_POSTS_PER_WEEK: Quota for AI-generated bot posts.
   • BOT_POST_COOLDOWN_SECONDS: Minimum time between AI bot posts.
   • BOT_SYSTEM_ENABLED: Kill switch for the AI bot generation system.

3. Seed the support bots:

   python run_seed.py

4. Run the Application:

   uvicorn main:app --reload

   The first startup automatically seeds a set of default forum categories if your database is empty, so the index isn't blank during local development.