# vopesh/product-review-forum architecture

> Architecture diagram of the GitHub repository vopesh/product-review-forum, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vopesh/product-review-forum
- Repository: https://github.com/vopesh/product-review-forum

## Overview

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/app.py`](https://github.com/vopesh/product-review-forum/blob/main/app/app.py) (App), [`app/api/routes/postRoutes.py`](https://github.com/vopesh/product-review-forum/blob/main/app/api/routes/postRoutes.py) (Post API), [`app/api/routes/authRoutes.py`](https://github.com/vopesh/product-review-forum/blob/main/app/api/routes/authRoutes.py) (Auth API), [`app/models/models.py`](https://github.com/vopesh/product-review-forum/blob/main/app/models/models.py) (ORM Models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client UI"]
  node_streamlit["Streamlit UI<br/>frontend client<br/>[streamlit_app.py]"]
end

subgraph group_backend["FastAPI Backend"]
  node_main(("Main<br/>entrypoint<br/>[main.py]"))
  node_app_assembly["App<br/>fastapi assembly<br/>[app.py]"]
  node_auth_routes["Auth API<br/>http routes<br/>[authRoutes.py]"]
  node_post_routes["Post API<br/>http routes<br/>[postRoutes.py]"]
  node_auth_schemas["Auth Schemas<br/>contracts<br/>[auth_schemas.py]"]
  node_post_schemas["Post Schemas<br/>contracts<br/>[post_schemas.py]"]
  node_models[("ORM Models<br/>sqlalchemy models<br/>[models.py]")]
  node_db[("Database<br/>async sqlAlchemy<br/>[db.py]")]
  node_base[("Base<br/>[base.py]")]
end

subgraph group_infra["Shared Infra"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_security["Security<br/>jwt auth<br/>[security.py]"]
  node_imagekit["ImageKit<br/>media integration<br/>[imagekit.py]"]
  node_exceptions{{"Errors<br/>[exceptions.py]"}}
  node_logger{{"Logger<br/>logging<br/>[logger.py]"}}
end

node_main -->|"boot"| node_app_assembly
node_app_assembly -->|"mounts"| node_auth_routes
node_app_assembly -->|"mounts"| node_post_routes
node_app_assembly -->|"initializes"| node_db
node_auth_routes -->|"validates"| node_auth_schemas
node_auth_routes -->|"auth"| node_security
node_auth_routes -->|"reads/writes"| node_models
node_post_routes -->|"validates"| node_post_schemas
node_post_routes -->|"reads/writes"| node_models
node_post_routes -->|"uploads"| node_imagekit
node_post_routes -->|"handles"| node_exceptions
node_models -->|"extends"| node_base
node_db -->|"configures"| node_config
node_security -->|"configures"| node_config
node_imagekit -->|"configures"| node_config
node_app_assembly -->|"logs"| node_logger
node_streamlit -.->|"calls api"| node_app_assembly

click node_main "https://github.com/vopesh/product-review-forum/blob/main/main.py"
click node_app_assembly "https://github.com/vopesh/product-review-forum/blob/main/app/app.py"
click node_auth_routes "https://github.com/vopesh/product-review-forum/blob/main/app/api/routes/authRoutes.py"
click node_post_routes "https://github.com/vopesh/product-review-forum/blob/main/app/api/routes/postRoutes.py"
click node_auth_schemas "https://github.com/vopesh/product-review-forum/blob/main/app/schemas/auth_schemas.py"
click node_post_schemas "https://github.com/vopesh/product-review-forum/blob/main/app/schemas/post_schemas.py"
click node_models "https://github.com/vopesh/product-review-forum/blob/main/app/models/models.py"
click node_db "https://github.com/vopesh/product-review-forum/blob/main/app/database/db.py"
click node_base "https://github.com/vopesh/product-review-forum/blob/main/app/database/base.py"
click node_config "https://github.com/vopesh/product-review-forum/blob/main/app/core/config.py"
click node_security "https://github.com/vopesh/product-review-forum/blob/main/app/core/security.py"
click node_imagekit "https://github.com/vopesh/product-review-forum/blob/main/app/core/imagekit.py"
click node_exceptions "https://github.com/vopesh/product-review-forum/blob/main/app/core/exceptions.py"
click node_logger "https://github.com/vopesh/product-review-forum/blob/main/app/core/logger.py"
click node_streamlit "https://github.com/vopesh/product-review-forum/blob/main/streamlit_app.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_streamlit toneBlue
class node_main,node_app_assembly,node_auth_routes,node_post_routes,node_auth_schemas,node_post_schemas,node_models,node_db,node_base toneAmber
class node_config,node_security,node_imagekit,node_exceptions,node_logger toneMint
```

## Components

### Client UI

Streamlit frontend that consumes the API

- [Streamlit UI](https://github.com/vopesh/product-review-forum/blob/main/streamlit_app.py): frontend client · User-facing review browsing and submission app · `streamlit_app.py`

### FastAPI Backend

API service, domain logic, and persistence

- [Main](https://github.com/vopesh/product-review-forum/blob/main/main.py): entrypoint · Backend process entrypoint · `main.py`
- [App](https://github.com/vopesh/product-review-forum/blob/main/app/app.py): fastapi assembly · Wires routes, startup, and middleware · `app/app.py`
- [Auth API](https://github.com/vopesh/product-review-forum/blob/main/app/api/routes/authRoutes.py): http routes · Registration, login, and current-user endpoints · `app/api/routes/authRoutes.py`
- [Post API](https://github.com/vopesh/product-review-forum/blob/main/app/api/routes/postRoutes.py): http routes · Feed, reviews, uploads, posts, and comments endpoints · `app/api/routes/postRoutes.py`
- [Auth Schemas](https://github.com/vopesh/product-review-forum/blob/main/app/schemas/auth_schemas.py): contracts · Auth request and response models · `app/schemas/auth_schemas.py`
- [Post Schemas](https://github.com/vopesh/product-review-forum/blob/main/app/schemas/post_schemas.py): contracts · Post and comment payload validation · `app/schemas/post_schemas.py`
- [ORM Models](https://github.com/vopesh/product-review-forum/blob/main/app/models/models.py): sqlalchemy models · Users, posts, comments, and media fields · `app/models/models.py`
- [Database](https://github.com/vopesh/product-review-forum/blob/main/app/database/db.py): async sqlAlchemy · Async engine and session setup · `app/database/db.py`
- [Base](https://github.com/vopesh/product-review-forum/blob/main/app/database/base.py): declarative base · Shared ORM base metadata · `app/database/base.py`

### Shared Infra

Cross-cutting configuration, security, logging, and error handling

- [Config](https://github.com/vopesh/product-review-forum/blob/main/app/core/config.py): settings · Environment-driven application settings · `app/core/config.py`
- [Security](https://github.com/vopesh/product-review-forum/blob/main/app/core/security.py): jwt auth · Password hashing and token handling · `app/core/security.py`
- [ImageKit](https://github.com/vopesh/product-review-forum/blob/main/app/core/imagekit.py): media integration · Cloud media upload and deletion boundary · `app/core/imagekit.py`
- [Errors](https://github.com/vopesh/product-review-forum/blob/main/app/core/exceptions.py): api errors · Standardized exception and response handling · `app/core/exceptions.py`
- [Logger](https://github.com/vopesh/product-review-forum/blob/main/app/core/logger.py): logging · Application logging setup · `app/core/logger.py`

## Connections

- 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