# marinasemak/final_project architecture

> Architecture diagram of the GitHub repository marinasemak/final_project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marinasemak/final_project
- Repository: https://github.com/marinasemak/final_project

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        Browser["Web/Mobile Client"]:::client
        SwaggerUI["Swagger UI"]:::client
    end

    %% API Layer
    subgraph "API Layer"
        Main["main.py"]:::entrypoint
        subgraph Routers
            UsersRouter["UsersRouter"]:::api
            PostsRouter["PostsRouter"]:::api
            CommentsRouter["CommentsRouter"]:::api
            ScoresRouter["ScoresRouter"]:::api
            TagsRouter["TagsRouter"]:::api
            UrlsRouter["UrlsRouter"]:::api
            AuthRouter["AuthRouter"]:::api
            HealthRouter["HealthRouter"]:::api
        end
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        UsersService["UsersService"]:::service
        PostsService["PostsService"]:::service
        CommentsService["CommentsService"]:::service
        ScoresService["ScoresService"]:::service
        TagsService["TagsService"]:::service
        UrlService["UrlService"]:::service
        AuthService["AuthService"]:::service
        MailUtils["MailUtils"]:::service
        CloudinaryService["CloudinaryService"]:::service
        QRService["QRService"]:::service
        HealthService["HealthChecker"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        UsersRepo["UsersRepository"]:::repo
        PostsRepo["PostsRepository"]:::repo
        CommentsRepo["CommentsRepository"]:::repo
        ScoresRepo["ScoresRepository"]:::repo
        TagsRepo["TagsRepository"]:::repo
        UrlRepo["UrlRepository"]:::repo
        DBFactory["DBSessionFactory"]:::db
    end

    %% Persistence & Infra
    subgraph "Persistence & Infra"
        DB[(PostgreSQL)]:::db
        Migrations["Migrations"]:::docs
        Docker["Docker Compose"]:::infra
        Env[".env/.env_example"]:::docs
    end

    %% External Services
    subgraph "External Services"
        Cloudinary["Cloudinary API"]:::external
        SMTP["SMTP Mail Service"]:::external
    end

    %% Configurations
    subgraph "Configuration"
        Config["Config"]:::docs
        CacheCfg["CacheConfig"]:::docs
        Consts["Constants"]:::docs
        Messages["Messages"]:::docs
    end

    %% Templates & Static
    subgraph "Frontend Assets"
        Static["Static Assets"]:::static
        Templates["HTML Templates"]:::static
    end

    %% Connections
    Browser -->|HTTP| Main
    SwaggerUI -->|Docs| Main

    Main -->|includes routers| UsersRouter
    Main --> PostsRouter
    Main --> CommentsRouter
    Main --> ScoresRouter
    Main --> TagsRouter
    Main --> UrlsRouter
    Main --> AuthRouter
    Main --> HealthRouter

    %% Routers to Services
    UsersRouter -->|calls| UsersService
    PostsRouter --> PostsService
    CommentsRouter --> CommentsService
    ScoresRouter --> ScoresService
    TagsRouter --> TagsService
    UrlsRouter --> UrlService
    AuthRouter --> AuthService
    HealthRouter --> HealthService

    %% Services to Repos & externals
    UsersService -->|CRUD| UsersRepo
    PostsService --> PostsRepo
    CommentsService --> CommentsRepo
    ScoresService --> ScoresRepo
    TagsService --> TagsRepo
    UrlService --> UrlRepo
    AuthService -->|JWT| Config
    AuthService -->|email| MailUtils
    MailUtils --> SMTP
    PostsService --> CloudinaryService
    CloudinaryService --> Cloudinary
    UrlService --> QRService
    QRService -->|generates| UrlService
    HealthService -->|db check| DBFactory

    %% Repos to DB
    UsersRepo --> DBFactory
    PostsRepo --> DBFactory
    CommentsRepo --> DBFactory
    ScoresRepo --> DBFactory
    TagsRepo --> DBFactory
    UrlRepo --> DBFactory

    DBFactory --> DB
    Migrations --> DB

    %% Config usage
    Main --> Config
    Main --> CacheCfg
    Main --> Consts
    Main --> Messages

    Env --> Config
    Docker --> DB
    Docker --> SMTP

    %% Click Events
    click Main "https://github.com/marinasemak/final_project/blob/main/main.py"
    click Config "https://github.com/marinasemak/final_project/blob/main/conf/config.py"
    click CacheCfg "https://github.com/marinasemak/final_project/blob/main/conf/cache.py"
    click Consts "https://github.com/marinasemak/final_project/blob/main/conf/const.py"
    click Messages "https://github.com/marinasemak/final_project/blob/main/conf/messages.py"
    click DBFactory "https://github.com/marinasemak/final_project/blob/main/database/db.py"
    click Migrations "https://github.com/marinasemak/final_project/tree/main/migrations/"
    click UsersRouter "https://github.com/marinasemak/final_project/blob/main/src/users/routes.py"
    click UsersService "https://github.com/marinasemak/final_project/blob/main/src/users/users_service.py"
    click UsersRepo "https://github.com/marinasemak/final_project/blob/main/src/users/repository.py"
    click UsersModels "https://github.com/marinasemak/final_project/blob/main/src/users/models.py"
    click UsersSchemas "https://github.com/marinasemak/final_project/blob/main/src/users/schemas.py"
    click PostsRouter "https://github.com/marinasemak/final_project/blob/main/src/posts/routes.py"
    click PostsService "https://github.com/marinasemak/final_project/blob/main/src/posts/post_service.py"
    click PostsRepo "https://github.com/marinasemak/final_project/blob/main/src/posts/repository.py"
    click PostsModels "https://github.com/marinasemak/final_project/blob/main/src/posts/models.py"
    click PostsSchemas "https://github.com/marinasemak/final_project/blob/main/src/posts/schemas.py"
    click CommentsRouter "https://github.com/marinasemak/final_project/blob/main/src/comments/router.py"
    click CommentsService "https://github.com/marinasemak/final_project/blob/main/src/comments/comments_services.py"
    click CommentsRepo "https://github.com/marinasemak/final_project/blob/main/src/comments/repository.py"
    click CommentsModels "https://github.com/marinasemak/final_project/blob/main/src/comments/models.py"
    click CommentsSchema "https://github.com/marinasemak/final_project/blob/main/src/comments/schema.py"
    click ScoresRouter "https://github.com/marinasemak/final_project/blob/main/src/scores/routes.py"
    click ScoresService "https://github.com/marinasemak/final_project/blob/main/src/scores/score_service.py"
    click ScoresRepo "https://github.com/marinasemak/final_project/blob/main/src/scores/repository.py"
    click ScoresModels "https://github.com/marinasemak/final_project/blob/main/src/scores/models.py"
    click ScoresSchemas "https://github.com/marinasemak/final_project/blob/main/src/scores/schemas.py"
    click TagsService "https://github.com/marinasemak/final_project/blob/main/src/tags/tag_service.py"
    click TagsRepo "https://github.com/marinasemak/final_project/blob/main/src/tags/repository.py"
    click TagsModels "https://github.com/marinasemak/final_project/blob/main/src/tags/models.py"
    click TagsSchemas "https://github.com/marinasemak/final_project/blob/main/src/tags/schemas.py"
    click UrlService "https://github.com/marinasemak/final_project/blob/main/src/urls/image_service.py"
    click UrlRepo "https://github.com/marinasemak/final_project/blob/main/src/urls/repository.py"
    click UrlModels "https://github.com/marinasemak/final_project/blob/main/src/urls/models.py"
    click AuthService "https://github.com/marinasemak/final_project/blob/main/src/services/auth/auth_service.py"
    click MailUtils "https://github.com/marinasemak/final_project/blob/main/src/services/auth/mail_utils.py"
    click AuthRouter "https://github.com/marinasemak/final_project/blob/main/src/services/auth/routes.py"
    click CloudinaryService "https://github.com/marinasemak/final_project/blob/main/src/services/cloudinary_service.py"
    click QRService "https://github.com/marinasemak/final_project/blob/main/src/services/qr_service.py"
    click HealthService "https://github.com/marinasemak/final_project/blob/main/src/services/healthchecker.py"
    click Docker "https://github.com/marinasemak/final_project/blob/main/docker-compose.yml"
    click Env "https://github.com/marinasemak/final_project/blob/main/.env_example"
    click pyproject "https://github.com/marinasemak/final_project/blob/main/pyproject.toml"
    click requirements "https://github.com/marinasemak/final_project/blob/main/requirements.txt"
    click alembic "https://github.com/marinasemak/final_project/blob/main/alembic.ini"

    %% Styles
    classDef client fill:#E3F2FD,stroke:#64B5F6,stroke-width:1px
    classDef entrypoint fill:#BBDEFB,stroke:#2196F3,stroke-width:1px
    classDef api fill:#C8E6C9,stroke:#388E3C,stroke-width:1px
    classDef service fill:#FFF9C4,stroke:#FBC02D,stroke-width:1px
    classDef repo fill:#FFE0B2,stroke:#FB8C00,stroke-width:1px
    classDef db fill:#D1C4E9,stroke:#7B1FA2,stroke-width:1px
    classDef external fill:#FCE4EC,stroke:#C2185B,stroke-width:1px
    classDef infra fill:#ECEFF1,stroke:#455A64,stroke-width:1px
    classDef docs fill:#F3E5F5,stroke:#8E24AA,stroke-width:1px
    classDef static fill:#E0F7FA,stroke:#00ACC1,stroke-width:1px
```
