How vopesh/product-review-forum works
1. Top-level shape
- This repo is a two-process app: a FastAPI backend under app/ and a separate Streamlit frontend in streamlit_app.py.
- The backend exposes the API, owns authentication, persistence, and media lifecycle. The frontend is a consumer of those APIs rather than the source of business logic.
2. Backend entry and app composition
- main.py is the backend entrypoint and likely boots the FastAPI app defined in app/app.py.
- app/app.py is the application assembly point: it wires routers, database startup, and any global middleware/lifespan behavior.
3. HTTP/API boundary
- The API is modularized by domain in app/api/routes/:
- authRoutes.py handles account/session endpoints.
- postRoutes.py handles reviews, feed, uploads, and comments.
- This keeps transport concerns isolated from the core data and storage logic.
4. Authentication subsystem
- Authentication is JWT-based, with password hashing in app/core/security.py.
- app/api/routes/authRoutes.py likely mediates registration, login, and “current user” operations.
- app/schemas/auth_schemas.py defines request/response contracts, while ORM user records live in app/models/models.py.
5. Review/post domain
- The main business object is a product review post: metadata plus optional media.
- app/api/routes/postRoutes.py owns the lifecycle for feed listing, creating uploads, fetching a user’s posts, and deleting posts in bulk or individually.
- app/schemas/post_schemas.py defines validation boundaries for create/list/comment payloads.
6. Commenting subsystem
- Comments are part of the public engagement model and are attached to posts.
- The README describes a 15-minute edit window, so comment update/delete logic is not purely CRUD; it includes time-based authorization rules.
- This is most likely enforced in the post routes or model layer, with the API rejecting edits outside the grace period.
7. Persistence layer
- app/database/db.py and app/database/base.py define the async database engine/session setup and shared declarative base.
- app/models/models.py contains the SQLAlchemy ORM entities for users, posts, comments, and any media-related fields.
- The app uses async SQLAlchemy with PostgreSQL/asyncpg, so the core data flow is: request → async route handler → async session → ORM → PostgreSQL.
8. Media storage and cleanup
- app/core/imagekit.py is the integration boundary to ImageKit, which is used for cloud hosting of images/videos.
- The architecture explicitly separates DB persistence from media persistence: media is uploaded to ImageKit, then the resulting reference/URL is stored in the database.
- Deletions are handled with background tasks and retry logic so media cleanup does not block API responses; Tenacity-based retries are used to recover from transient storage failures.
9. Failure handling and consistency
- app/core/exceptions.py and the README indicate a focus on transactional safety and orphan prevention.
- If DB persistence fails after a successful upload, the system tries to delete the remote file immediately to avoid orphaned media.
- This means the consistency boundary is split across two systems: PostgreSQL is the source of truth for records, while ImageKit holds the actual binary assets.
10. Cross-cutting infrastructure
- app/core/config.py centralizes environment-driven configuration such as database URL, ImageKit credentials, and JWT secret.
- app/core/logger.py provides application logging, and app/core/exceptions.py likely standardizes API error responses.
- These modules are shared infrastructure, not domain logic.
11. Frontend role
- streamlit_app.py is the user-facing UI layer for browsing feeds, submitting reviews, and interacting with comments.
- It is architecturally separate from the backend and should be diagrammed as a client of the FastAPI API, not as part of the service core.
12. Startup behavior and operational note
- The README says tables are created automatically on startup in app/app.py, so the backend currently owns schema bootstrapping.
- For a production architecture diagram, it’s worth marking this as a startup-time DB initialization concern, with a note that migrations are not yet the primary mechanism.
Main entry points: app.py App · postRoutes.py Post API · authRoutes.py Auth API · models.py ORM Models
Components 15
Client UI
Streamlit frontend that consumes the API
- Streamlit UI · User-facing review browsing and submission app
streamlit_app.py
FastAPI Backend
API service, domain logic, and persistence
- Main · Backend process entrypoint
main.py - App · Wires routes, startup, and middleware
app/app.py - Auth API · Registration, login, and current-user endpoints
app/api/routes/authRoutes.py - Post API · Feed, reviews, uploads, posts, and comments endpoints
app/api/routes/postRoutes.py - Auth Schemas · Auth request and response models
app/schemas/auth_schemas.py - Post Schemas · Post and comment payload validation
app/schemas/post_schemas.py - ORM Models · Users, posts, comments, and media fields
app/models/models.py - Database · Async engine and session setup
app/database/db.py - Base · Shared ORM base metadata
app/database/base.py
Shared Infra
Cross-cutting configuration, security, logging, and error handling
- Config · Environment-driven application settings
app/core/config.py - Security · Password hashing and token handling
app/core/security.py - ImageKit · Cloud media upload and deletion boundary
app/core/imagekit.py - Errors · Standardized exception and response handling
app/core/exceptions.py - Logger · Application logging setup
app/core/logger.py
Connections 17
- Main → App: boot · Starts the FastAPI application
- App → Auth API: mounts · Registers auth endpoints
- App → Post API: mounts · Registers post and comment endpoints
- App → Database: initializes · Creates tables and database startup resources
- Auth API → Auth Schemas: validates · Uses auth request and response contracts
- Auth API → Security: auth · Hashes passwords and issues or verifies tokens
- Auth API → ORM Models: reads/writes · Persists user records
- Post API → Post Schemas: validates · Uses post and comment payload contracts
- Post API → ORM Models: reads/writes · Persists posts, comments, and media references
- Post API → ImageKit: uploads · Stores and removes remote media assets
- Post API → Errors: handles · Converts domain failures to API errors
- ORM Models → Base: extends · Builds ORM entities on shared declarative base
- Database → Config: configures · Uses environment settings for database access
- Security → Config: configures · Uses JWT and hashing settings
- ImageKit → Config: configures · Uses media service credentials
- App → Logger: logs · Shares application logging
- Streamlit UI → App: calls api · Consumes backend endpoints as a client