Add Reddit monitoring bot — backend, frontend, and Docker config

Python/FastAPI backend with PostgreSQL for collecting Reddit data via
public .json endpoints. React/Vite dashboard for analytics. Docker Compose
setup with API and worker services connecting to shared PostgreSQL.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

backend/models/__init__.py

@@ -0,0 +1,19 @@
+from backend.models.base import Base
+from backend.models.subreddit import MonitoredSubreddit
+from backend.models.author import Author
+from backend.models.post import Post
+from backend.models.comment import Comment
+from backend.models.metric_snapshot import MetricSnapshot
+from backend.models.daily_digest import DailyDigest
+from backend.models.summary import Summary
+
+__all__ = [
+    "Base",
+    "MonitoredSubreddit",
+    "Author",
+    "Post",
+    "Comment",
+    "MetricSnapshot",
+    "DailyDigest",
+    "Summary",
+]

backend/models/author.py

@@ -0,0 +1,23 @@
+from datetime import datetime, timezone
+from sqlalchemy import String, Integer, DateTime
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class Author(Base):
+    __tablename__ = "authors"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    username: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    first_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    last_seen_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    total_posts: Mapped[int] = mapped_column(Integer, default=0)
+    total_comments: Mapped[int] = mapped_column(Integer, default=0)
+
+    posts: Mapped[list["Post"]] = relationship(back_populates="author")  # noqa: F821
+    comments: Mapped[list["Comment"]] = relationship(back_populates="author")  # noqa: F821

backend/models/base.py

@@ -0,0 +1,5 @@
+from sqlalchemy.orm import DeclarativeBase
+
+
+class Base(DeclarativeBase):
+    pass

backend/models/comment.py

@@ -0,0 +1,34 @@
+from datetime import datetime, timezone
+from sqlalchemy import String, Integer, DateTime, ForeignKey
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class Comment(Base):
+    __tablename__ = "comments"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    reddit_id: Mapped[str] = mapped_column(String(20), unique=True, nullable=False)
+    post_id: Mapped[int] = mapped_column(ForeignKey("posts.id"), nullable=False, index=True)
+    parent_comment_id: Mapped[int | None] = mapped_column(
+        ForeignKey("comments.id"), index=True
+    )
+    author_id: Mapped[int | None] = mapped_column(ForeignKey("authors.id"), index=True)
+    body: Mapped[str] = mapped_column(nullable=False)
+    score: Mapped[int] = mapped_column(Integer, default=0)
+    created_utc: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    collected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+    post: Mapped["Post"] = relationship(back_populates="comments")  # noqa: F821
+    author: Mapped["Author | None"] = relationship(back_populates="comments")  # noqa: F821
+    parent_comment: Mapped["Comment | None"] = relationship(
+        remote_side="Comment.id", foreign_keys=[parent_comment_id]
+    )

backend/models/daily_digest.py

@@ -0,0 +1,22 @@
+from datetime import date, datetime, timezone
+from sqlalchemy import Date, DateTime, ForeignKey, JSON
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class DailyDigest(Base):
+    __tablename__ = "daily_digests"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    subreddit_id: Mapped[int] = mapped_column(
+        ForeignKey("monitored_subreddits.id"), nullable=False
+    )
+    digest_date: Mapped[date] = mapped_column(Date, nullable=False)
+    content: Mapped[str] = mapped_column(nullable=False)
+    metadata_: Mapped[dict | None] = mapped_column("metadata", JSON)
+    generated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    subreddit: Mapped["MonitoredSubreddit"] = relationship(back_populates="daily_digests")  # noqa: F821

backend/models/metric_snapshot.py

@@ -0,0 +1,23 @@
+from datetime import datetime, timezone
+from sqlalchemy import Integer, Float, DateTime, ForeignKey, Index
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class MetricSnapshot(Base):
+    __tablename__ = "metric_snapshots"
+    __table_args__ = (
+        Index("ix_metric_snapshots_post_snapshot", "post_id", "snapshot_at"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    post_id: Mapped[int] = mapped_column(ForeignKey("posts.id"), nullable=False)
+    score: Mapped[int] = mapped_column(Integer, nullable=False)
+    num_comments: Mapped[int] = mapped_column(Integer, nullable=False)
+    upvote_ratio: Mapped[float | None] = mapped_column(Float)
+    snapshot_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    post: Mapped["Post"] = relationship(back_populates="metric_snapshots")  # noqa: F821

backend/models/post.py

@@ -0,0 +1,42 @@
+from datetime import datetime, timezone
+from sqlalchemy import String, Boolean, Integer, Float, DateTime, ForeignKey, Index
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class Post(Base):
+    __tablename__ = "posts"
+    __table_args__ = (
+        Index("ix_posts_subreddit_created", "subreddit_id", "created_utc"),
+    )
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    reddit_id: Mapped[str] = mapped_column(String(20), unique=True, nullable=False)
+    subreddit_id: Mapped[int] = mapped_column(ForeignKey("monitored_subreddits.id"), index=True)
+    author_id: Mapped[int | None] = mapped_column(ForeignKey("authors.id"), index=True)
+    title: Mapped[str] = mapped_column(nullable=False)
+    selftext: Mapped[str | None] = mapped_column()
+    url: Mapped[str | None] = mapped_column()
+    permalink: Mapped[str | None] = mapped_column()
+    flair: Mapped[str | None] = mapped_column(String(255))
+    score: Mapped[int] = mapped_column(Integer, default=0, index=True)
+    upvote_ratio: Mapped[float | None] = mapped_column(Float)
+    num_comments: Mapped[int] = mapped_column(Integer, default=0)
+    is_self: Mapped[bool | None] = mapped_column(Boolean)
+    over_18: Mapped[bool] = mapped_column(Boolean, default=False)
+    hot_rank: Mapped[int | None] = mapped_column(Integer)
+    created_utc: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    collected_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+    subreddit: Mapped["MonitoredSubreddit"] = relationship(back_populates="posts")  # noqa: F821
+    author: Mapped["Author | None"] = relationship(back_populates="posts")  # noqa: F821
+    comments: Mapped[list["Comment"]] = relationship(back_populates="post")  # noqa: F821
+    metric_snapshots: Mapped[list["MetricSnapshot"]] = relationship(back_populates="post")  # noqa: F821

backend/models/subreddit.py

@@ -0,0 +1,28 @@
+from datetime import datetime, timezone
+from sqlalchemy import String, Boolean, Integer, DateTime
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class MonitoredSubreddit(Base):
+    __tablename__ = "monitored_subreddits"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255), unique=True, nullable=False)
+    display_name: Mapped[str | None] = mapped_column(String(255))
+    description: Mapped[str | None] = mapped_column()
+    subscribers: Mapped[int | None] = mapped_column(Integer)
+    is_active: Mapped[bool] = mapped_column(Boolean, default=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(timezone.utc),
+        onupdate=lambda: datetime.now(timezone.utc),
+    )
+
+    posts: Mapped[list["Post"]] = relationship(back_populates="subreddit")  # noqa: F821
+    daily_digests: Mapped[list["DailyDigest"]] = relationship(back_populates="subreddit")  # noqa: F821
+    summaries: Mapped[list["Summary"]] = relationship(back_populates="subreddit")  # noqa: F821

backend/models/summary.py

@@ -0,0 +1,25 @@
+from datetime import datetime, timezone
+from sqlalchemy import String, DateTime, ForeignKey, JSON
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.base import Base
+
+
+class Summary(Base):
+    __tablename__ = "summaries"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    subreddit_id: Mapped[int] = mapped_column(
+        ForeignKey("monitored_subreddits.id"), nullable=False
+    )
+    summary_type: Mapped[str] = mapped_column(String(50), nullable=False)
+    content: Mapped[str | None] = mapped_column()
+    metadata_: Mapped[dict | None] = mapped_column("metadata", JSON)
+    period_start: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    period_end: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    provider: Mapped[str | None] = mapped_column(String(100))
+    generated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), default=lambda: datetime.now(timezone.utc)
+    )
+
+    subreddit: Mapped["MonitoredSubreddit"] = relationship(back_populates="summaries")  # noqa: F821