How marinasemak/final_project works
Project type and purpose
• PhotoShare is a web-based, service-oriented, full-stack (API-centric) photo-sharing application built with FastAPI.
• It exposes REST endpoints, serves a minimal set of HTML templates and static assets, and delegates core logic to domain-specific modules (users, posts, comments, scores, tags, URLs).
File structure
• Entrypoint: main.py
• Configuration: conf/ (cache, config, constants, messages)
• Database layer:
• database/db.py (SQLAlchemy session factory)
• migrations/ (Alembic scripts)
• Domain modules under src/:
• users, posts, comments, scores, tags, urls
• Each follows a router → service → repository → models/schemas pattern
• Cross-cutting services under src/services:
• auth (JWT, email utilities)
• cloudinary_service, qr_service, healthchecker
• Static assets & templates for minimal front-end.
• Docker compose for Postgres + mail service; environment managed via .env/.env_example.
Key insights from README
• REST API with JWT auth and role-based access (users, moderators, admins).
• PostgreSQL + SQLAlchemy ORM.
• Cloudinary for image storage/transformations.
• QR code generation for photo URLs.
• Swagger UI for documentation.
Main components
A. Client Layer
• Web Browser / Mobile App (HTTP clients)
• Swagger UI (interactive API docs)
B. API Layer (FastAPI server)
• main.py → FastAPI instance
• Routers: users, posts, comments, scores, tags, urls, auth, healthchecker
C. Business Logic Layer
• Services:
• users_service, post_service, comment_service, score_service, tag_service, url_service
• auth_service, mail_utils, cloudinary_service, qr_service, healthchecker
D. Data Access Layer
• Repositories for each domain (users, posts, comments, scores, tags, urls)
• database/db.py (SessionLocal, engine)
E. Persistence
• PostgreSQL (hosted in Docker Compose)
• Alembic migrations
F. External Services
• Cloudinary API
• Mail service (SMTP container)
G. Supporting Components
• Cache (if used via conf/cache.py)
• Configuration service (conf/config.py)
Relationships & interactions
• Client sends HTTP request → FastAPI router
• Router delegates to corresponding Service
• Service may:
• Validate input, check roles (Auth Service)
• Transform images (Cloudinary Service)
• Generate QR codes (QR Service)
• Call repository for CRUD operations
• Repository interacts with SQLAlchemy Session → PostgreSQL
• Service triggers emails via Mail Service (SMTP)
• On startup: Healthchecker registers with FastAPI /health endpoint
Architectural patterns & design principles
• Layered architecture (API → Service → Repository → Database)
• Dependency injection via FastAPI’s Depends()
• Separation of concerns (domain modules, auth module, external-service modules)
• Role-based access control enforced in auth_service
• Infrastructure as code: Docker Compose + Alembic migrations
• Service dependencies (auth, cloudinary, qr).
• Docker Compose cluster (Postgres + SMTP) as part of deployment infra.
• Security boundary: JWT issuance/validation in AuthService.