Repository navigation
Description
🎯 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()
endPhase 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()
endPhase 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()
endPhase 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.exswith local PostgreSQL credentials - Configure
config/test.exsfor 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.jswith 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_elixirtomix.exsdependencies:{: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
userstable 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 formatsettings 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
.gitignorefor 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.serverstarts the application - Visiting
http://localhost:4000shows 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
topicstable migration with all fields - Create
peopletable migration with tier enum - Create
definitionstable migration with tier and position - Create
topic_relationshipstable 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 (
/browseand/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
expressionstable with type enum - Create
expression_topicsjoin table - Create
bookstable - Create
websitestable - 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
mediatable with type enum - Create
media_topicsjoin table - Create
media_peoplejoin 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
votestable (polymorphic) - Vote aggregation and scoring
- Voting LiveView components
- Vote-based ordering within tiers
6.2 Bot Curators
- Create
botstable - Create
bot_influencestable - 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 | 📱 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."
Activity
holden commentedon Sep 18, 2026
Closing as a superseded planning document: the README's status table and decision log are the living record since MVP-0 (2026-09-07), and the current trackers are #109 (providers), #116 (multi-source shelves), #111 (the page), #105 (exemplars), #101 (assessor), #97 (personas). The vision issues #45/#46 and the design/layer issues #65/#66/#67/#63/#17 stay open.