Skip to content

🎯 Master Plan: Devil's Dictionary Phoenix Rebuild - Complete Phased Roadmap #61

Open
Open
🎯 Master Plan: Devil's Dictionary Phoenix Rebuild - Complete Phased Roadmap#61

Description

@holden
holden
opened on Jan 27, 2026

🎯 Master Plan: Devil's Dictionary Phoenix Rebuild

Consolidates: #44, #45, #46, #47, #48, #59, #60

"The dead know better. The living just have opinions."

This is the definitive implementation roadmap for rebuilding Devil's Dictionary as a Phoenix/Elixir application. It synthesizes all previous planning issues into a single, phased execution plan.

📋 Executive Summary

Vision: A hierarchical knowledge platform where the stratification of truth is made explicit and visible—from aristocratic dead intellectuals to the plebeian chaos of social media.

Tech Stack:

  • Framework: Phoenix 1.7+ with LiveView
  • Database: PostgreSQL 15+
  • Auth: Clerk (clerk_elixir)
  • UI: Tailwind CSS + Oatmeal Theme (Tailwind Plus)
  • Background Jobs: Oban
  • Caching: Cachex
  • HTTP Client: Req

Core Principle: The layout itself is the argument. Visual hierarchy communicates the stratification of knowledge sources.

🗂️ Complete Schema Overview

Phase 1: Core Content (MVP)

# Topics - Core content organization
schema "topics" do
  field :title, :string
  field :slug, :string                    # URL identifier, unique
  field :type, Ecto.Enum, values: [
    :concept, :thing, :place, :event, 
    :action, :person, :organization, :other
  ]
  field :pronunciation, :string           # Optional phonetic
  field :part_of_speech, :string          # noun, verb, adj, etc.
  field :definition_count, :integer, default: 0
  
  # Display handling (from #60)
  field :display_type, Ecto.Enum, 
    values: [:standard, :redirect, :disambiguation], 
    default: :standard
  belongs_to :redirect_to, Topic          # For pure redirects only
  
  timestamps()
end

# People - Authors, creators, notable figures
schema "people" do
  field :name, :string
  field :slug, :string
  field :birth_date, :date
  field :death_date, :date                # nil = living (Middle Class tier)
  field :bio, :text
  field :photo_url, :string
  field :tier, Ecto.Enum, values: [:aristocracy, :middle, :plebs]
  
  # External IDs for API enrichment
  field :google_knowledge_id, :string
  field :tmdb_id, :integer
  field :open_library_id, :string
  field :wikidata_id, :string
  
  timestamps()
end

# Definitions - Multi-source definitions per topic
schema "definitions" do
  belongs_to :topic, Topic
  belongs_to :author, Person              # nullable
  
  field :content, :text                   # The definition text
  field :source_name, :string             # "The Devil's Dictionary"
  field :source_url, :string
  field :source_year, :integer            # 1911
  field :tier, Ecto.Enum, values: [:aristocracy, :middle, :plebs]
  field :position, :integer               # Display order within tier
  
  timestamps()
end

# Topic Relationships - Semantic connections (from #60)
schema "topic_relationships" do
  belongs_to :topic, Topic
  belongs_to :related_topic, Topic
  
  field :relationship_type, Ecto.Enum, values: [
    # MVP (Phase 1)
    :word_form,      # aristocracy ↔ aristocratic
    :synonym,        # truth ↔ verity
    :related,        # truth → honesty
    :see_also,       # editorial connection
    
    # Phase 2+
    :antonym,        # truth ↔ lie
    :broader,        # aristocracy → government
    :narrower,       # government → aristocracy
    :disambiguates   # bank → bank_finance, bank_geography
  ]
  
  field :bidirectional, :boolean, default: true
  field :weight, :float, default: 1.0
  
  timestamps()
end

Phase 2: Expressions Layer

# Expressions - Quotes, lyrics, poems
schema "expressions" do
  field :type, Ecto.Enum, values: [:quote, :lyric, :poem]
  field :content, :text
  field :attribution_text, :string        # "Oscar Wilde"
  belongs_to :author, Person              # Resolved author (nullable)
  
  field :source_title, :string            # "The Importance of Being Earnest"
  field :source_url, :string
  field :tier, Ecto.Enum, values: [:aristocracy, :middle, :plebs]
  
  # Quote-specific
  field :disputed, :boolean, default: false
  field :misattributed, :boolean, default: false
  
  timestamps()
end

# Expression-Topic join (many-to-many)
schema "expression_topics" do
  belongs_to :expression, Expression
  belongs_to :topic, Topic
  timestamps()
end

# Books - Sources for definitions/quotes
schema "books" do
  field :title, :string
  field :slug, :string
  belongs_to :author, Person
  field :open_library_id, :string
  field :publication_year, :integer
  timestamps()
end

# Websites - External sources
schema "websites" do
  field :title, :string
  field :url, :string
  field :tier, Ecto.Enum, values: [:aristocracy, :middle, :plebs]
  timestamps()
end

Phase 3: Media Layer

# Media - Photos, art, GIFs, movies, TV shows
schema "media" do
  field :type, Ecto.Enum, values: [:movie, :tv_show, :photo, :art, :gif]
  field :title, :string
  field :description, :text
  field :url, :string
  field :thumbnail_url, :string
  
  # Source tracking
  field :source_type, :string             # "tmdb", "unsplash", "giphy"
  field :source_id, :string
  field :tier, Ecto.Enum, values: [:aristocracy, :middle, :plebs]
  
  timestamps()
end

# Media-Topic join
schema "media_topics" do
  belongs_to :media, Media
  belongs_to :topic, Topic
  timestamps()
end

# Media-Person join (with roles)
schema "media_people" do
  belongs_to :media, Media
  belongs_to :person, Person
  field :role, :string                    # "director", "actor", "photographer"
  timestamps()
end

Phase 4: Community Layer (Future)

# Votes - Polymorphic voting
schema "votes" do
  field :votable_type, :string            # "Definition", "Expression"
  field :votable_id, :integer
  field :voter_type, :string              # "User" or "Bot"
  field :voter_id, :integer
  field :vote_flag, :boolean              # true = upvote, false = downvote
  field :vote_weight, :float, default: 1.0
  timestamps()
end

# Bots - AI curators with personalities
schema "bots" do
  field :name, :string
  field :personality, :text
  field :base_model, :string
  field :voter_weight, :float, default: 1.0
  field :curation_focus, {:array, :string}
  timestamps()
end

# Bot Influences - Dead author influences on bots
schema "bot_influences" do
  belongs_to :bot, Bot
  belongs_to :person, Person
  field :influence_weight, :float, default: 1.0
  timestamps()
end

🎨 UI/UX Design System

Template Foundation: Oatmeal (Tailwind Plus)

Why Oatmeal works:

  • Literary, calm aesthetic matches dictionary gravitas
  • Typography-forward design perfect for definitions
  • Warm neutrals complement our tier system colors
  • Clean enough to let tier styling shine

Tier-Specific Color Systems

/* 👑 ARISTOCRACY - Gilded Authority */
--aristocracy-gold: #b8860b;      /* Dark Goldenrod - Frames, accents */
--aristocracy-brass: #8b7355;     /* Antique Brass - Text highlights */
--aristocracy-paper: #faf8f5;     /* Aged paper start */
--aristocracy-aged: #f5f0e0;      /* Aged paper end */
--aristocracy-border: #d4a574;    /* Tan - Double borders */
--aristocracy-text: #3d3d3d;      /* Charcoal - Serif, weighty */

/* 📚 MIDDLE CLASS - Clean Aspiration */
--middle-primary: #64748b;        /* Slate - Headers, accents */
--middle-secondary: #94a3b8;      /* Slate 400 - Borders */
--middle-background: #ffffff;     /* Clean white */
--middle-border: #e2e8f0;         /* Slate 200 - Subtle single border */
--middle-text: #334155;           /* Slate 700 - Sans-serif, modern */

/* 📱 THE PLEBS - Raw Democracy */
--plebs-primary: #6366f1;         /* Indigo - Links, interactions */
--plebs-secondary: #a855f7;       /* Purple - Highlights */
--plebs-background: #f8fafc;      /* Slate 50 - Social feed gray */
--plebs-text: #475569;            /* Slate 600 - Sans-serif, casual */

/* 🌐 GLOBAL - Oatmeal Base */
--page-bg: #fafaf9;               /* Stone 50 - Warm neutral */
--header: #1c1917;                /* Stone 900 - Deep, authoritative */
--links: #a16207;                 /* Amber 700 - Warm, literary */
--success: #059669;               /* Emerald 600 */
--muted: #78716c;                 /* Stone 500 */

Typography System

/* 👑 ARISTOCRACY */
font-family: 'Playfair Display', Georgia, serif;
font-weight: 600-700;
font-size: lg → 2xl for definitions;
style: italic for attribution, small-caps for names;

/* 📚 MIDDLE CLASS */
font-family: 'Inter', system-ui, sans-serif;
font-weight: 400-500;
font-size: base → lg;
style: clean, professional;

/* 📱 THE PLEBS */
font-family: 'Inter', system-ui, sans-serif;
font-weight: 400;
font-size: sm → base;
style: casual, emoji-friendly;

Tailwind Config Extension

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        aristocracy: {
          gold: '#b8860b',
          brass: '#8b7355',
          paper: '#faf8f5',
          aged: '#f5f0e0',
          border: '#d4a574',
        },
        // middle uses default slate
        plebs: {
          feed: '#f8fafc',
          // uses default indigo/purple
        }
      },
      fontFamily: {
        aristocracy: ['Playfair Display', 'Georgia', 'serif'],
        body: ['Inter', 'system-ui', 'sans-serif'],
      },
      backgroundImage: {
        'aged-paper': 'linear-gradient(to bottom, #faf8f5, #f5f0e0)',
      }
    }
  }
}

📐 Wireframes

1. Topic Detail Page (Desktop)

┌──────────────────────────────────────────────────────────────────────────┐
│  [Logo: Devil's Dictionary]                    [Search 🔍]  [Browse A-Z] │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  TRUTH                                                        noun │  │
│  │  /truːθ/                                                          │  │
│  │  ────────────────────────────────────────────────────────────────│  │
│  │  Word Family: truthful • truthfully                               │  │
│  │  Synonyms: verity • veracity                                      │  │
│  │  Related: honesty • reality • fact • sincerity                    │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  Topic Completeness: ██████░░░░ 3 of 5 layers                           │
│                                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│  ░░░░░░░░░░░░░░░░░ AGED PAPER TEXTURE ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
│                                                                          │
│  👑 THE ARISTOCRACY                                                      │
│  ═══════════════════                                                     │
│                                                                          │
│  ╔════════════════════════════════════════════════════════════════════╗  │
│  ║                                                                    ║  │
│  ║   "An ingenious compound of desirability and appearance."          ║  │
│  ║                                                                    ║  │
│  ║                              — AMBROSE BIERCE                      ║  │
│  ║                    The Devil's Dictionary, 1911                    ║  │
│  ║                                                                    ║  │
│  ╚════════════════════════════════════════════════════════════════════╝  │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │   "Conformity of notion to reality; that which is in               │  │
│  │    accord with fact or agreement."                                 │  │
│  │                                                                    │  │
│  │                              — SAMUEL JOHNSON                      │  │
│  │           A Dictionary of the English Language, 1755              │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  📚 THE SCHOLARLY                                                        │
│  ─────────────────                                                       │
│                                                                          │
│  The quality or state of being true. Most often used to mean             │
│  being in accord with fact or reality, or fidelity to an                 │
│  original or standard.                                                   │
│                                                                          │
│  — Wikipedia                                             [Read more →]   │
│                                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  📱 THE PLEBS SPEAK                                                      │
│  ──────────────────                                                      │
│                                                                          │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │ Urban Dictionary                                  👍 2.3k  👎 234 │   │
│  │                                                                  │   │
│  │ truth: when ur girl asks where u were and u actually tell        │   │
│  │ her lmaooo                                                       │   │
│  │                                                                  │   │
│  │ "I told her the truth bro, I was at Dave's playing 2K"          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  💬 WHAT THEY SAID                                                       │
│  ─────────────────                                                       │
│                                                                          │
│  "The truth will set you free, but first it will piss you off."         │
│                                                        — Gloria Steinem │
│                                                                          │
│  "There are no facts, only interpretations."                            │
│                                                    — Friedrich Nietzsche │
│                                                                          │
│                                                     [+ 47 more quotes →] │
│                                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│  ← Previous: TRUMP                           Next: TRUTHFUL →           │
├──────────────────────────────────────────────────────────────────────────┤
│  [Logo]          About  |  Browse  |  Authors  |  Philosophy            │
│                  © 2026 Devil's Dictionary. The dead know better.        │
└──────────────────────────────────────────────────────────────────────────┘

2. Browse A-Z Page

┌──────────────────────────────────────────────────────────────────────────┐
│  [Logo: Devil's Dictionary]                    [Search 🔍]  [Browse A-Z] │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  BROWSE THE DICTIONARY                                                   │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │  A  B  C  D  E  F  G  H  I  J  K  L  M                            │  │
│  │  N  O  P  Q  R  S  [T]  U  V  W  X  Y  Z                          │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  T — 127 TOPICS                                                          │
│  ═══════════════════════════════════════════════════════════════════════ │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │ 👑 TRUTH, n.                                       ██████░░░░ 3/5 │  │
│  │    "An ingenious compound of desirability and appearance."        │  │
│  │                                              — Ambrose Bierce     │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  ┌────────────────────────────────────────────────────────────────────┐  │
│  │    TECHNOLOGY, n.                                  ██░░░░░░░░ 1/5 │  │
│  │    [No aristocratic definition — only plebeian content]           │  │
│  │                                                   [View anyway →] │  │
│  └────────────────────────────────────────────────────────────────────┘  │
│                                                                          │
│  [Showing 4 of 127]                                    [Load more ↓]    │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

3. Person/Author Page

┌──────────────────────────────────────────────────────────────────────────┐
│  [Logo: Devil's Dictionary]                    [Search 🔍]  [Browse A-Z] │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐ │
│  │  ┌───────────────┐                                                  │ │
│  │  │               │    AMBROSE BIERCE                                │ │
│  │  │    [Photo]    │    1842 — 1914 (disappeared)                     │ │
│  │  │               │                                                  │ │
│  │  │               │    👑 Aristocracy Tier                           │ │
│  │  └───────────────┘    American journalist, short story writer,      │ │
│  │                       and satirist. Best known for his sardonic      │ │
│  │                       wit and "The Devil's Dictionary."              │ │
│  └─────────────────────────────────────────────────────────────────────┘ │
│                                                                          │
├──────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  DEFINITIONS BY AMBROSE BIERCE                                           │
│  ══════════════════════════════════════════════════════════════════════ │
│                                                                          │
│  Showing 998 of 998 definitions                        [Sort: A-Z ▼]    │
│                                                                          │
│  ╔════════════════════════════════════════════════════════════════════╗  │
│  ║  ABSTAINER, n.                                                     ║  │
│  ║  "A weak person who yields to the temptation of denying himself   ║  │
│  ║   a pleasure."                                                     ║  │
│  ╚════════════════════════════════════════════════════════════════════╝  │
│                                                                          │
│  [Load more ↓]                                                           │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

4. Empty Topic Fallback (Word Form)

┌────────────────────────────────────────────────────────────────────────┐
│  ARISTOCRATICAL, adj.                                                  │
│  /əˌrɪstəˈkrætɪkəl/                                                   │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │  An archaic form of ARISTOCRATIC.                                │ │
│  │                                                                  │ │
│  │  → See ARISTOCRATIC for definitions                              │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  Word Family: aristocracy • aristocratic                               │
└────────────────────────────────────────────────────────────────────────┘

5. Disambiguation Page

┌────────────────────────────────────────────────────────────────────────┐
│  BANK                                                                  │
│                                                                        │
│  Bank may refer to:                                                    │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │  BANK (finance)                                                  │ │
│  │  A financial institution that accepts deposits and makes loans.  │ │
│  │  → 5 definitions                                                 │ │
│  └──────────────────────────────────────────────────────────────────┘ │
│                                                                        │
│  ┌──────────────────────────────────────────────────────────────────┐ │
│  │  BANK (geography)                                                │ │
│  │  The land alongside a river or body of water.                    │ │
│  │  → 2 definitions                                                 │ │
│  └──────────────────────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘

🚀 Implementation Phases

═══════════════════════════════════════════════════════════════════════

PHASE 0: PROJECT FOUNDATION

═══════════════════════════════════════════════════════════════════════

Goal: Fully configured Phoenix project ready for development

0.1 Development Environment

  • Ensure Elixir 1.15+ and Erlang/OTP 26+ installed
  • Ensure PostgreSQL 15+ installed and running
  • Ensure Node.js 18+ installed (for asset pipeline)
  • Create project directory structure

0.2 Phoenix Project Creation

  • Create Phoenix project with PostgreSQL: 
    mix phx.new devils_dictionary --database postgresql
cd devils_dictionary
  • Configure config/dev.exs with local PostgreSQL credentials
  • Configure config/test.exs for test database
  • Create and migrate databases: 
    mix ecto.create
mix ecto.migrate
  • Verify Phoenix starts: mix phx.server

0.3 Tailwind CSS Setup

  • Verify Tailwind CSS installed (included in Phoenix 1.7+)
  • Configure assets/tailwind.config.js with custom colors: 
    module.exports = {
  content: ["./js/**/*.js", "../lib/*_web.ex", "../lib/*_web/**/*.*ex"],
  theme: {
    extend: {
      colors: {
        aristocracy: {
          gold: '#b8860b',
          brass: '#8b7355',
          paper: '#faf8f5',
          aged: '#f5f0e0',
          border: '#d4a574',
        },
        plebs: {
          feed: '#f8fafc',
        }
      },
      fontFamily: {
        aristocracy: ['Playfair Display', 'Georgia', 'serif'],
        body: ['Inter', 'system-ui', 'sans-serif'],
      },
      backgroundImage: {
        'aged-paper': 'linear-gradient(to bottom, #faf8f5, #f5f0e0)',
      }
    }
  },
  plugins: [
    require("@tailwindcss/forms"),
    require("@tailwindcss/typography"),
  ]
}
  • Add Google Fonts (Playfair Display, Inter) to root.html.heex

0.4 Oatmeal Theme Installation

  • Copy Oatmeal theme files from Tailwind Plus to vendors/ folder
  • Import Oatmeal base styles into assets/css/app.css
  • Configure Oatmeal color palette as foundation
  • Verify theme renders correctly on default page

0.5 LiveView Configuration

  • Verify LiveView is enabled (default in Phoenix 1.7+)
  • Configure LiveView socket in endpoint.ex
  • Set up live reload for development
  • Create basic LiveView layout template

0.6 Authentication Setup (Clerk)

  • Add clerk_elixir to mix.exs dependencies: 
    {:clerk_elixir, "~> 0.1"}
  • Configure Clerk credentials in config/runtime.exs: 
    config :clerk_elixir,
  secret_key: System.get_env("CLERK_SECRET_KEY"),
  publishable_key: System.get_env("CLERK_PUBLISHABLE_KEY")
  • Create Clerk JWT verification Plug
  • Add authentication routes
  • Create users table migration (clerk_user_id, email, metadata)
  • Test Clerk sign-in/sign-out flow

0.7 Core Dependencies

  • Add core dependencies to mix.exs: 
    {:req, "~> 0.4"},           # HTTP client
{:floki, "~> 0.35"},        # HTML parsing
{:slugify, "~> 1.3"},       # Slug generation
{:oban, "~> 2.17"},         # Background jobs
{:cachex, "~> 3.6"},        # Caching
  • Run mix deps.get
  • Configure Oban in config/config.exs
  • Configure Cachex for API response caching
  • Create Oban migrations: mix ecto.gen.migration add_oban_jobs_table

0.8 Project Structure

  • Create context directories: 
    lib/devils_dictionary/
├── accounts/          # User management
├── content/           # Topics, Definitions, Relationships
├── people/            # People, Books
├── expressions/       # Quotes, Lyrics, Poems (Phase 2)
├── media/             # Movies, Photos, GIFs (Phase 4)
└── external_apis/     # API clients
  • Create web directory structure for components
  • Set up basic error pages (404, 500)

0.9 Development Tooling

  • Configure mix format settings in .formatter.exs
  • Add Credo for code analysis: {:credo, "~> 1.7", only: [:dev, :test]}
  • Add Dialyxir for type checking: {:dialyxir, "~> 1.4", only: [:dev], runtime: false}
  • Configure .gitignore for Elixir/Phoenix project
  • Create seed file structure in priv/repo/seeds.exs

0.10 Verification

  • Phoenix server starts without errors
  • PostgreSQL connection works
  • Tailwind CSS compiles and hot-reloads
  • Oatmeal theme styles visible
  • LiveView socket connects
  • Clerk authentication flow works
  • All tests pass: mix test

Acceptance Criteria:

  • Running mix phx.server starts the application
  • Visiting http://localhost:4000 shows styled page with Oatmeal theme
  • Can sign in/out via Clerk
  • Database migrations run without errors
  • Hot reload works for both Elixir and CSS changes

═══════════════════════════════════════════════════════════════════════

PHASE 1: MVP CONTENT

═══════════════════════════════════════════════════════════════════════

Goal: Browsable dictionary with tiered definitions and visual hierarchy

1.1 Core Schema (Topics, People, Definitions)

  • Create topics table migration with all fields
  • Create people table migration with tier enum
  • Create definitions table migration with tier and position
  • Create topic_relationships table migration
  • Implement Ecto schemas with validations
  • Implement slug generation with Slugify
  • Add definition_count counter cache trigger

1.2 Topic Relationships

  • Implement relationship types: word_form, synonym, related, see_also
  • Create bidirectional relationship logic (Ecto.Multi)
  • Add validation for circular redirects
  • Implement relationship limits per topic
  • Create relationship management functions

1.3 Seed Data

  • Parse Ambrose Bierce's Devil's Dictionary from Gutenberg text
  • Create seed script for ~1000 Bierce definitions
  • Create Ambrose Bierce person record (Aristocracy tier)
  • Parse Samuel Johnson definitions for key words
  • Create Samuel Johnson person record (Aristocracy tier)
  • Seed The Verge New Devil's Dictionary (Middle tier)
  • Run seeds: mix run priv/repo/seeds.exs

1.4 LiveView Components

  • AristocraticDefinitionCard - gilded frames, serif fonts, aged paper
  • MiddleClassCard - clean borders, sans-serif, white bg
  • PlebsCard - minimal borders, social aesthetic
  • TieredDefinitions - organizes and renders definitions by tier
  • TopicCompleteness - visual progress bar showing layer coverage
  • WordFamily - displays morphological variants
  • Synonyms - displays synonym relationships
  • RelatedTopics - sidebar with semantic connections
  • TopicHeader - title, pronunciation, part of speech

1.5 Public Pages

  • Topic Detail Page (/topics/:slug)
    • Fetch topic with preloaded definitions, relationships
    • Tiered definitions display (Aristocracy → Middle → Plebs)
    • Word family section
    • Synonyms section
    • Related topics sidebar
    • Completeness indicator
    • Previous/Next navigation
    • Empty topic fallback ("See X")
    • Redirect handling (HTTP 301)
    • Disambiguation page rendering
  • Browse A-Z (/browse and /browse/:letter)
    • Letter navigation component
    • Topic cards with preview and completeness
    • Infinite scroll or pagination
    • Filter by tier availability
  • Search (/search)
    • Real-time LiveView search with debouncing
    • Type-ahead suggestions
    • Results grouped with tier indicators
    • Full-text PostgreSQL search
  • Person Page (/people/:slug)
    • Bio and photo display
    • Tier badge (Aristocracy/Middle/Plebs)
    • All definitions by this author
    • Pagination for large definition counts

1.6 Navigation & Layout

  • Header component with logo, search, browse link
  • Footer component with links
  • Mobile-responsive navigation
  • Breadcrumb component

1.7 Admin Features (Basic)

  • Admin authentication (Clerk role-based)
  • Topic CRUD interface
  • Definition CRUD interface
  • Person CRUD interface
  • Relationship management interface
  • Seed status dashboard

Acceptance Criteria:

  • Can browse 1000+ topics A-Z
  • Topic pages show tiered definitions with distinct visual styling
  • Visual hierarchy is immediately apparent (gilded vs clean vs social)
  • Word forms and synonyms cross-reference correctly
  • Empty topics show "See X" fallback
  • Search works with real-time results
  • Person pages show all their definitions
  • Mobile experience works

═══════════════════════════════════════════════════════════════════════

PHASE 2: EXPRESSIONS & QUOTES LAYER

═══════════════════════════════════════════════════════════════════════

Goal: "What They Said" section with quotes, lyrics, and poems

2.1 Expressions Schema

  • Create expressions table with type enum
  • Create expression_topics join table
  • Create books table
  • Create websites table
  • Implement author resolution from attribution_text

2.2 API Infrastructure

  • Set up GenServer supervision tree for API clients
  • Configure Cachex with TTL strategies per source
  • Set up Oban queues for API jobs
  • Implement rate limiting behavior
  • Add retry logic with exponential backoff
  • Create API client behavior module

2.3 WikiQuotes Integration

  • WikiQuotes GenServer client
  • Parse HTML responses with Floki
  • Create Quote expressions from results
  • Background job: FetchQuotesJob
  • 24-hour cache

2.4 PoetryDB Integration

  • PoetryDB GenServer client
  • Create Poem expressions
  • Link poems to topics by keyword matching

2.5 UI: What They Said Section

  • Quote card component with attribution
  • Poem card component with formatting
  • "What They Said" section on topic pages
  • Collapsible quotes list with "Show more"

Acceptance Criteria:

  • Topics have auto-discovered quotes
  • Quotes attributed to authors with links
  • Poems display with proper formatting
  • Expression count visible on topic pages

═══════════════════════════════════════════════════════════════════════

PHASE 3: PLEBEIAN LAYER

═══════════════════════════════════════════════════════════════════════

Goal: Visual contrast between aristocratic and plebeian content

3.1 Urban Dictionary Integration

  • Urban Dictionary GenServer client (via RapidAPI)
  • Parse slang definitions
  • Store thumbs up/down counts
  • Create Plebs-tier definitions

3.2 UI: The Plebs Speak Section

  • Social card component with emoji/vote counts
  • "The Plebs Speak" section at bottom of topic pages
  • Raw, social-media aesthetic styling
  • Visual contrast with gilded aristocracy sections

Acceptance Criteria:

  • Clear visual hierarchy: Aristocracy (top) → Middle → Plebs (bottom)
  • Plebeian content styled like social media cards
  • The juxtaposition is jarring and intentional

═══════════════════════════════════════════════════════════════════════

PHASE 4: MEDIA LAYER

═══════════════════════════════════════════════════════════════════════

Goal: "How Culture Sees It" with movies, photos, GIFs, art

4.1 Media Schema Implementation

  • Create media table with type enum
  • Create media_topics join table
  • Create media_people join table with roles

4.2 Giphy Integration

  • Giphy GenServer client
  • G-rated filter
  • Create Gif media records
  • 1-hour cache

4.3 Unsplash Integration

  • Unsplash GenServer client
  • Photographer attribution
  • Create Photo media records

4.4 TMDB Integration

  • TMDB GenServer client
  • Search movies and TV shows
  • Fetch cast and crew
  • Create Movie/TvShow media records
  • Link media to people with roles

4.5 UI: How Culture Sees It

  • Media gallery component
  • Movie/TV card with poster
  • Photo card with attribution
  • GIF display with playback
  • Grid layout for media section

Acceptance Criteria:

  • Topics have auto-discovered GIFs, photos, movies
  • Media gallery displays on topic pages
  • Movies/TV linked to people (actors, directors)
  • Photographers credited for Unsplash photos

═══════════════════════════════════════════════════════════════════════

PHASE 5: ENRICHMENT & RELATIONSHIPS

═══════════════════════════════════════════════════════════════════════

Goal: Semantic connections and people enrichment

5.1 Knowledge Graph Integration

  • Knowledge Graph GenServer client
  • Search people and entities
  • Enrich Person records with descriptions, images
  • Background job: EnrichPersonJob

5.2 OpenLibrary Integration

  • OpenLibrary GenServer client
  • Search authors
  • Fetch book details
  • Create Book records
  • Enrich Person birth/death dates

5.3 ConceptNet Integration

  • ConceptNet GenServer client
  • Fetch semantic relationships
  • Auto-create topic_relationships
  • Map ConceptNet relations to our types

5.4 Datamuse Integration

  • Datamuse GenServer client
  • Word associations
  • Related word suggestions

5.5 Advanced Relationship Types

  • Implement antonym relationships
  • Implement broader/narrower (taxonomy)
  • Implement disambiguation display type
  • Disambiguation page UI

Acceptance Criteria:

  • People have Knowledge Graph descriptions and images
  • Books auto-created from OpenLibrary
  • Topics have auto-discovered semantic relationships
  • Disambiguation pages work correctly

═══════════════════════════════════════════════════════════════════════

PHASE 6: COMMUNITY FEATURES (FUTURE)

═══════════════════════════════════════════════════════════════════════

Goal: Voting, bots, and user contributions

6.1 Voting System

  • Create votes table (polymorphic)
  • Vote aggregation and scoring
  • Voting LiveView components
  • Vote-based ordering within tiers

6.2 Bot Curators

  • Create bots table
  • Create bot_influences table
  • Bot personality system
  • Bot voting with weighted influence

6.3 User Contributions

  • User-submitted definitions (Plebs tier by default)
  • Moderation queue
  • Canonization system (rising from Plebs)

═══════════════════════════════════════════════════════════════════════

PHASE 7: AI LAYER (FUTURE)

═══════════════════════════════════════════════════════════════════════

Goal: Resurrected dead authors via AI

7.1 Dead Author Personas

  • OpenAI/Anthropic integration
  • Dead author persona prompts
  • "What would Bierce say about NFTs?"
  • Clear 🤖 labeling as AI-generated

7.2 AI Definitions

  • Generate definitions for modern terms
  • Bierce-style satire generation
  • Oscar Wilde, Mark Twain personas
  • User-triggered generation

═══════════════════════════════════════════════════════════════════════

PHASE 8: SOCIAL LAYER (FUTURE)

═══════════════════════════════════════════════════════════════════════

Goal: Real-time social content

  • Twitter/X API integration
  • Reddit API integration
  • Meme APIs (Imgflip, Tenor)
  • "Trending Now" section
  • Real-time feed component

🔌 API Integration Roadmap

Phase Source Type Priority Data
1 Bierce (seed) 👑 Aristocracy 🔴 Critical ~1000 definitions
1 Johnson (seed) 👑 Aristocracy 🔴 Critical Historical definitions
2 WikiQuotes 📚 Middle 🔴 Critical Quotes
2 PoetryDB 📚 Middle 🟡 Medium Poems
3 Urban Dictionary 📱 Plebs 🟠 High Slang definitions
4 Giphy 📱 Plebs 🟠 High GIFs
4 Unsplash 📚 Middle 🟠 High Photos
4 TMDB 📚 Middle 🟠 High Movies, TV
5 Knowledge Graph 🔗 Meta 🟡 Medium People enrichment
5 OpenLibrary 🔗 Meta 🟡 Medium Books, authors
5 ConceptNet 🔗 Meta 🟡 Medium Semantic relations
5 Datamuse 🔗 Meta 🟢 Low Word associations
7 OpenAI/Anthropic 🤖 AI 🟢 Low AI definitions
8 Twitter/X 📱 Plebs 🟢 Low Tweets
8 Reddit 📱 Plebs 🟢 Low Posts

📊 Success Metrics

Phase 0 (Foundation)

  • Phoenix app runs locally without errors
  • PostgreSQL connected and migrations work
  • Tailwind + Oatmeal theme rendering
  • Clerk authentication functional
  • All dev tooling configured

MVP (Phases 0-3)

  • 1000+ Bierce definitions seeded
  • 100+ Johnson definitions seeded
  • Visual hierarchy immediately apparent
  • Sub-3-second page loads
  • Mobile-responsive design

Full Product (Phases 4-5)

  • 5+ sources per popular topic
  • Auto-enriched people profiles
  • Semantic relationships discovered
  • User engagement > 2 pages/session

Future (Phases 6-8)

  • Active bot curators
  • User contributions flowing
  • AI definitions generating engagement
  • Social content creating relevance

📚 References

Issue Title Focus
#44 Complete Phoenix Rebuild Technical architecture
#45 Construction of Truth Philosophical framework
#46 Aristocracy of Truth Hierarchy concept
#47 Layered Content Architecture Source stacking, UI
#48 MVP Phoenix Rebuild Core MVP scope
#59 UI/UX Design System Colors, typography, wireframes
#60 Topic Relationships Word forms, disambiguation

🏷️ Labels

master-plan epic phoenix elixir mvp roadmap ui-ux

"The dead know better. The living just have opinions."

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions