# abel-asfaw/photography-portfolio architecture

> Architecture diagram of the GitHub repository abel-asfaw/photography-portfolio, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abel-asfaw/photography-portfolio
- Repository: https://github.com/abel-asfaw/photography-portfolio

## Overview

##### Project Type and Purpose
- This is a full-stack web application (“Photography Portfolio”) whose primary function is to let authenticated users upload, view, and delete photos.
- Frontend: React + TypeScript
- Backend: FastAPI (Python)
- Storage: Amazon S3 (for binary assets) and PostgreSQL (for metadata)
- Authentication: Auth0
- Deployed via Docker containers orchestrated with docker-compose and fronted by Nginx

##### File Structure Analysis
- Top-level “api” folder: FastAPI service
- src/main.py – entrypoint (uvicorn)
- routers/photos.py – upload/retrieve/delete endpoints
- config.py / database.py / models.py / schemas.py – DB & S3 configuration
- Dockerfile & .dockerignore
- Top-level “client” folder: React application
- src/App.tsx, components/, hooks/, api/ – UI, API client, queries
- package.json, tsconfig.json, Dockerfile, .dockerignore
- public/index.html, assets/images
- Deployment files
- docker-compose.yaml – defines containers + network
- default.conf – Nginx reverse-proxy config
- .prettierignore, .gitignore, etc.

##### Key Architectural Insights from README
- Single-host, containerized stack accessible at localhost:3005
- Auth0 protects upload/delete routes on both client and server
- External services: S3 bucket (photo storage), Auth0 (OAuth/JWT), PostgreSQL (metadata)

##### Main Components
a. User’s Web Browser (React Frontend)
b. Nginx Reverse Proxy (listening on 3005)
c. FastAPI Backend Service
d. PostgreSQL Database
e. Amazon S3 Bucket
f. Auth0 Identity Provider

##### Relationships & Data Flows
- Browser → (HTTPS) → Nginx
- Static assets (React JS/CSS) served directly from client container or via Nginx
- API calls (prefixed /api) forwarded to FastAPI
- React → Auth0
- Redirects for login, receives JWT
- React → FastAPI
- JWT Bearer token in Authorization header
- Endpoints: GET /photos, POST /photos, DELETE /photos
- FastAPI → PostgreSQL
- CRUD on photo metadata
- FastAPI → S3
- Upload binary data, generate presigned URLs for GET
- FastAPI → Auth0
- Optionally to verify tokens (JWKS endpoint)

##### Architectural Patterns & Principles
- Container-per-component pattern via Docker Compose
- API Gateway pattern (Nginx as reverse proxy)
- Layered architecture:
- Presentation layer (React)
- API layer (FastAPI routers, schemas)
- Data layer (PostgreSQL, S3)
- Secure by design: JWT authentication enforced at both client and server

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and External Services
    Browser["User Browser"]:::browser
    Auth0["Auth0\n(Identity Provider)"]:::external
    S3["Amazon S3\n( Photo Storage )"]:::external

    %% Docker Network Boundary
    subgraph "Docker Network" 
        direction TB
        Nginx["Nginx Reverse Proxy\nport 3005"]:::container
        React["React Client\nport 3000"]:::container
        FastAPI["FastAPI Service\nport 8000"]:::container
        Postgres["PostgreSQL\nport 5432"]:::db
    end

    %% Connections
    Browser -->|"HTTPS /api/photos"| Nginx
    Nginx -->|"Serves Static Assets"| React
    Nginx -->|"Proxies API Calls"| FastAPI
    Browser -->|"> Redirect & JWT"| Auth0
    React -->|"JWT Bearer Token"| FastAPI
    FastAPI -->|"SQL Queries"| Postgres
    FastAPI -->|"Upload / Presigned URL"| S3
    FastAPI --o|"JWKS Token Validation"| Auth0
    Browser --o|"OAuth Redirect / Token"| Auth0

    %% Click Events
    click React "https://github.com/abel-asfaw/photography-portfolio/tree/main/client/"
    click FastAPI "https://github.com/abel-asfaw/photography-portfolio/blob/main/api/src/main.py"
    click Postgres "https://github.com/abel-asfaw/photography-portfolio/blob/main/api/src/database.py"
    click S3 "https://github.com/abel-asfaw/photography-portfolio/blob/main/api/src/config.py"
    click Auth0 "https://github.com/abel-asfaw/photography-portfolio/blob/main/client/src/components/AuthGuard.tsx"
    click Nginx "https://github.com/abel-asfaw/photography-portfolio/blob/main/default.conf"
    click Browser "https://github.com/abel-asfaw/photography-portfolio/blob/main/client/src/App.tsx"

    %% Styling
    classDef browser fill:#f9f,stroke:#333,stroke-width:2px,shape:round;
    classDef container fill:#bbf,stroke:#333,stroke-width:1px;
    classDef db fill:#bfb,stroke:#333,stroke-width:1px,shape:cylinder;
    classDef external fill:#ffb,stroke:#333,stroke-width:1px;
```
