Contents
Build the container before the contents
Reading an entire X timeline is not realistic, but you still want to know what people said about a topic today. TopicDigestX is a web app that takes keywords, collects related posts, and returns a digest summarized by an LLM.
What runs today is only the container. Collection through the X API, LLM summarization, and async task processing are not implemented, and the README says so plainly: the backend skeleton is done, and the X API client, LLM integration, and async processing are planned. This post covers how that skeleton — FastAPI, PostgreSQL, and an Alembic layer that is planned but not yet present — is put together, and where it currently stops.
Architecture
Three containers and the configuration between them.
React + Vite :3000"] -->|"/api/*"| PX["Vite proxy
strips /api"] PX --> API["FastAPI
uvicorn :8000"] API --> CFG["Settings
pydantic-settings"] CFG --> ENV[".env / environment"] API -->|"implemented (dummy)"| STUB["/topics /digest stubs"] API -.->|"not connected"| DB[("PostgreSQL 15
:5432")] MIG["Alembic (not installed)"] -.-> DB
Figure 1: TopicDigestX components and their current state (dotted lines are unimplemented)
The split is narrow:
- Browser: React 19 with Vite. Only requests starting with
/apiare forwarded to the backend. - FastAPI: port 8000. Routes, configuration loading, and stub endpoints for topics.
- PostgreSQL 15: port 5432. The container starts, but nothing reads or writes it yet.
The db service in docker-compose.yml has a pg_isready health check (interval: 5s, retries: 5).
Technology choices
| Question | Chosen | Alternative | Why |
|---|---|---|---|
| API | FastAPI 0.115 | Flask | OpenAPI is generated from type hints, and Depends injects settings and sessions |
| Configuration | pydantic-settings | Reading os.environ directly |
Types and defaults live in one place, and .env and real env vars look the same |
| ORM | SQLAlchemy (declarative_base) |
Hand-written SQL | Models stay Python classes, which Alembic autogenerate can consume |
| Migrations | Alembic (planned, not installed) | Base.metadata.create_all() |
Keeps a history; create_all cannot alter an existing table |
Core implementation
1. Configuration lives in Pydantic Settings
Settings in backend/main.py folds environment variables and .env into one type.
# backend/main.py
class Settings(BaseSettings):
x_bearer_token: str = "default_bearer_token"
openai_api_key: str = "default_openai_key"
database_url: str = "sqlite:///./test.db"
secret_key: str = "default_secret"
llm_model_name: str = "gpt-3.5-turbo"
model_config = SettingsConfigDict(env_file='../.env', env_file_encoding='utf-8', extra='ignore')
Because of extra='ignore', an unknown key in .env does not stop startup. get_settings() is wrapped in @lru_cache() and injected with Depends, so the file is not re-read on every request.
The /config endpoint returns only database_url_type (the type name) and llm_model_name. The point is to have a debugging endpoint that cannot leak a connection string or a key.
2. Sessions stay inside database.py
# backend/database.py
engine = create_engine(SQLALCHEMY_DATABASE_URL, pool_pre_ping=True)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()
def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
pool_pre_ping=True is insurance against holding a connection that died when the database restarted. Making get_db a generator means close() runs as soon as the Depends scope ends.
3. One table, shaped so Alembic can take over
The first model is Topic alone. Keywords are a single Text column rather than a second table.
# backend/model.py
class Topic(Base):
__tablename__ = "topics"
id = Column(Integer, primary_key=True, index=True)
name = Column(String, index=True, nullable=False)
keywords = Column(Text, nullable=True)
created_at = Column(DateTime, server_default=func.now())
updated_at = Column(DateTime, server_default=func.now(), onupdate=func.now())
server_default=func.now() puts the default on the database side, so it does not depend on the application clock. If migrations will create the table, defining these columns in database terms up front avoids a later ALTER just to add a default.
Alembic, however, is still on the README’s planned list: there is no alembic.ini and no versions/ directory. Nothing creates the table yet, and /topics returns hard-coded JSON.
4. Route everything through /api with the Vite proxy
// frontend/vite.config.ts
proxy: {
'/api': {
target: 'http://backend:8000',
changeOrigin: true,
rewrite: (path) => path.replace(/^\/api/, ''),
},
},
The browser only ever sees localhost:3000, so no CORS configuration is needed. App.tsx calls /api/, the proxy rewrites it to /, and the request lands on the backend root.
Quality and performance
There are no benchmarks, load tests, or automated tests yet (there is no tests/ directory). The only quality claims available are structural.
| Concern | Implementation | Effect |
|---|---|---|
| Dropped connections | pool_pre_ping=True |
Avoids reusing a connection that died |
| Config reads | @lru_cache() |
.env is not re-read per request |
| Secrets | /config exposes only a type name and model name |
No connection string or key in a response |
I am not quoting performance numbers because the repository records none. Cost only becomes interesting once collection and summarization exist, and that is the right place to measure.
Pitfalls
- SQLAlchemy is missing from the dependencies:
backend/pyproject.tomllists fastapi, uvicorn, pydantic-settings, and psycopg2-binary, but not SQLAlchemy or Alembic, even thoughdatabase.pyandmodel.pyimport them. Neither appears inuv.lock, sodatabase.pyfails at import time today. The containers start; the database layer does not. - Inconsistent import style:
backend/model.pyuses a relative import (from .database import Base), whilebackend/database.pyuses an absolute one (from main import Settings). Underuvicorn main:app,mainis not a package, somodel.pyneedsfrom database import Base. - The
.envpath depends on the working directory:env_file='../.env'resolves against the current directory. In Compose,backend/is mounted at/appwithWORKDIR /app, so that path points at/. The app still starts because the real values arrive as environment variables injected byenv_file: .env, but local runs and containers behave differently.
Takeaways
- Split settings, sessions, and models, and you know where to touch when a feature arrives.
- Dependency and import consistency breaks before the code does; check
pyproject.tomlagainst the imports. - If Alembic is coming, push defaults to the database side (
server_default) early.
Today the app starts, reads configuration, and answers with stubs. Nothing writes to the database yet. The next steps are adding SQLAlchemy and Alembic, creating the first revision under versions/, and replacing /topics with real data.
Related posts
- Cutting the Cost of Knowing What Is Trending on X
- Summarizing an X timeline automatically: designing a topic digest system with FastAPI and an LLM (in Japanese)
Building an information pipeline or an LLM summarizer of your own?
I take on technical consulting and development support.
See also
- Co-evolving Four Roles, GAN-Style: The Testbed Behind umigame_GAN
- Detecting Duplicate Images with dHash and Hamming Distance in a Chrome Extension
- Less Time Searching the Cargo Area: A Load Plan That Does Not Cram the Van
- Loading 80 Parcels into a Kei Van in Seconds: Extreme Points and an Independent Validator
- Folding the Search for a Repost's Origin into One Query