# guilhermetorresm/cloud-storage-app architecture

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

- Interactive diagram: https://gitdiagram.com/guilhermetorresm/cloud-storage-app
- Repository: https://github.com/guilhermetorresm/cloud-storage-app

## Overview

1. **Repository shape**
   - This is a monorepo with two deployable applications: a **FastAPI backend** in `backend/` and a **React frontend** in `frontend/`.
   - The backend is organized as a layered/clean architecture; the frontend is organized by pages, reusable components, and service wrappers for API access.

2. **Backend architectural style**
   - The backend is split into `presentation`, `application`, `domain`, and `infrastructure`, with shared utilities in `shared`.
   - That separation is important: HTTP concerns stay in `presentation`, business rules live in `domain`, orchestration lives in `application`, and persistence/auth implementations live in `infrastructure`.

3. **Request flow on the backend**
   - A request enters FastAPI routes under `presentation/api/v1` such as `auth.py`, `users.py`, and `health.py`.
   - Routes delegate to application use cases, which operate on DTOs and domain entities instead of database models.
   - Errors are centralized through `presentation/middleware/error_handler.py`.

4. **Domain model**
   - The main implemented business area is **user management and authentication**.
   - The domain contains a `User` entity, user-specific domain exceptions, domain events, and multiple value objects such as `Email`, `Username`, `Password`, `HashedPassword`, `UserId`, `FirstName`, `LastName`, and profile-related fields.
   - This suggests strong validation and invariants are enforced in the domain rather than only in API schemas.

5. **Application layer responsibilities**
   - Use cases under `application/use_cases/user` and `application/use_cases/auth` implement workflows like create user, login, update profile, change password, and get current user.
   - DTOs in `application/dtos` bridge the API and business logic.
   - `application/services/password_service.py` defines the abstraction used by use cases, keeping hashing/verification out of the use cases themselves.

6. **Infrastructure adapters**
   - The infrastructure layer contains concrete implementations for JWT/auth, password hashing, database connection, SQLAlchemy models, and repository implementations.
   - `infrastructure/di/container.py` is the composition root that wires interfaces to implementations.
   - The repository interface in the domain is backed by a SQLAlchemy-based `user_repository.py` and `user_model.py`.

7. **Persistence and migrations**
   - PostgreSQL is the backing database, with SQLAlchemy for ORM mapping and Alembic for schema migrations.
   - The presence of `alembic/versions/...criocao_tabela_user.py` indicates the current schema focus is the user table.
   - Helper scripts like `scripts/setup_database.py` and `scripts/check_db_connection.py` support environment bootstrap and verification.

8. **Authentication boundary**
   - JWT is a central cross-cutting concern: the backend has a JWT service in infrastructure and shared auth utilities in `shared/auth_utils.py`.
   - The frontend has corresponding auth helpers, a private route component, and a user auth hook, indicating token-based session handling on the client side.
   - This creates a clear boundary: the frontend stores/uses tokens, while the backend validates them and resolves the current user.

9. **Frontend structure and data flow**
   - The React app is organized around `Pages`, `Components`, `Routes`, `Hooks`, `Services`, and `Utils`.
   - `Services/api.js`, `Services/auth.js`, and `Utils/fetchWithAuth.js` centralize HTTP access to the backend.
   - Pages such as login, register, profile, edit profile, edit password, and dashboard indicate the UI is centered on authenticated user workflows.

10. **UI composition**
    - Shared UI includes sidebar/topbar variants and small reusable controls under `Components/ui`.
    - Routing is handled separately in `Routes/appRoutes.js`, with `privateRouter.jsx` enforcing authenticated access to protected views.
    - This makes the frontend a thin orchestration layer over backend APIs rather than a state-heavy client.

11. **Files/S3 area**
    - The README describes cloud file upload and AWS S3 integration, and the tree includes scaffolding for `application/use_cases/files` and `infrastructure/storage` / `infrastructure/external`.
    - However, the visible implementation is concentrated in auth/user management, so the file-storage subsystem appears planned or partially scaffolded rather than fully represented in the tree.

12. **Testing strategy**
    - The backend has layered tests: unit tests for domain/application/infrastructure, integration tests for API and database, and an end-to-end test for file operations.
    - This mirrors the architecture boundaries and suggests the repo is designed to validate business rules separately from HTTP and persistence behavior.
    - The frontend includes standard React testing setup as well.

13. **Deployment and runtime**
    - Both apps are containerized with Dockerfiles, and each side has its own `docker-compose.yml` for local orchestration.
    - Backend runtime is Python 3.11 with FastAPI/Uvicorn; frontend runtime is Node/React 19.
    - The README’s architecture implies the main runtime topology is: browser → React app → FastAPI API → PostgreSQL, with AWS S3 as the external file storage target.

14. **What to highlight in an architecture diagram**
    - Show two client/server boundaries: the browser-facing React app, and the API/backend service.
    - Inside the backend, show the dependency direction from API routes to use cases to domain, then out to repositories/services in infrastructure.
    - Add PostgreSQL as the persistence store, JWT as the auth mechanism, and AWS S3 as the intended external object-storage integration.

Main entry points: [`backend/src/cloud_storage_app/application/use_cases/user/create_user_use_case.py`](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/application/use_cases/user/create_user_use_case.py) (Use Cases), [`backend/src/cloud_storage_app/presentation/api/v1/auth.py`](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/presentation/api/v1/auth.py) (API v1), [`backend/src/cloud_storage_app/infrastructure/di/container.py`](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/di/container.py) (DI Container), [`frontend/src/Routes/appRoutes.js`](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Routes/appRoutes.js) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser(("Browser<br/>client"))
  node_fe_routes["Routes<br/>routing<br/>[appRoutes.js]"]
  node_fe_private["Private Route<br/>auth guard<br/>[privateRouter.jsx]"]
  node_fe_auth_hook["Auth Hook<br/>session state<br/>[userAuth.js]"]
  node_fe_services["API Services<br/>http client<br/>[api.js]"]
  node_fe_pages["User Pages<br/>screens<br/>[login.jsx]"]
  node_fe_ui["Shared UI<br/>components<br/>[Sidebar.jsx]"]
end

subgraph group_backend["Backend"]
  node_api_entry(("FastAPI App<br/>entrypoint<br/>[main.py]"))
  node_api_routes["API v1<br/>presentation<br/>[auth.py]"]
  node_api_errors["Error Handler<br/>middleware<br/>[error_handler.py]"]
  node_app_use_cases["Use Cases"]
  node_app_dtos["DTOs<br/>contracts<br/>[user_dtos.py]"]
  node_domain_user{{"User Domain<br/>[user.py]"}}
  node_domain_repo["Repo Interface<br/>domain port<br/>[user_repository.py]"]
  node_domain_pwd["Password Port<br/>domain service"]
  node_infra_container["DI Container<br/>composition root<br/>[container.py]"]
  node_infra_auth["JWT & Crypto<br/>infrastructure<br/>[jwt_service.py]"]
  node_infra_db[("DB Layer<br/>persistence<br/>[connection.py]")]
  node_storage_target[("Object Storage<br/>external storage")]
  node_shared_auth["Auth Utils<br/>shared<br/>[auth_utils.py]"]
  node_files_uc["Files Use Cases<br/>planned application"]
end

node_browser -->|"opens app"| node_fe_routes
node_fe_routes -->|"protects"| node_fe_private
node_fe_private -->|"checks session"| node_fe_auth_hook
node_fe_routes -->|"renders"| node_fe_pages
node_fe_pages -->|"calls API"| node_fe_services
node_fe_pages -->|"composes"| node_fe_ui
node_fe_services -->|"requests"| node_api_entry
node_api_entry -->|"mounts"| node_api_routes
node_api_routes -->|"handled by"| node_api_errors
node_api_routes -->|"delegates"| node_app_use_cases
node_app_use_cases -->|"uses"| node_app_dtos
node_app_use_cases -->|"operates on"| node_domain_user
node_app_use_cases -->|"reads/writes"| node_domain_repo
node_app_use_cases -->|"verifies passwords"| node_domain_pwd
node_infra_container -->|"injects"| node_api_routes
node_infra_container -->|"binds"| node_infra_auth
node_infra_container -->|"binds"| node_infra_db
node_infra_auth -->|"shares"| node_shared_auth
node_infra_db -->|"implements"| node_domain_repo
node_infra_db -->|"maps"| node_domain_user
node_app_use_cases -.->|"extends to"| node_files_uc
node_files_uc -.->|"targets"| node_storage_target

click node_fe_routes "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Routes/appRoutes.js"
click node_fe_private "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Components/privateRouter.jsx"
click node_fe_auth_hook "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Hooks/userAuth.js"
click node_fe_services "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Services/api.js"
click node_fe_pages "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Pages/login.jsx"
click node_fe_ui "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Components/Sidebar.jsx"
click node_api_entry "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/main.py"
click node_api_routes "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/presentation/api/v1/auth.py"
click node_api_errors "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/presentation/middleware/error_handler.py"
click node_app_use_cases "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/application/use_cases/user/create_user_use_case.py"
click node_app_dtos "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/application/dtos/user_dtos.py"
click node_domain_user "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/domain/entities/user.py"
click node_domain_repo "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/domain/repositories/user_repository.py"
click node_domain_pwd "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/domain/services/password_service.py"
click node_infra_container "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/di/container.py"
click node_infra_auth "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/auth/jwt_service.py"
click node_infra_db "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/database/connection.py"
click node_storage_target "https://github.com/guilhermetorresm/cloud-storage-app/tree/main/backend/src/cloud_storage_app/infrastructure/storage"
click node_shared_auth "https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/shared/auth_utils.py"
click node_files_uc "https://github.com/guilhermetorresm/cloud-storage-app/tree/main/backend/src/cloud_storage_app/application/use_cases/files"

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_browser,node_fe_routes,node_fe_private,node_fe_auth_hook,node_fe_services,node_fe_pages,node_fe_ui toneBlue
class node_api_entry,node_api_routes,node_api_errors,node_app_use_cases,node_app_dtos,node_domain_user,node_domain_repo,node_domain_pwd,node_infra_container,node_infra_auth,node_infra_db,node_storage_target,node_shared_auth,node_files_uc toneAmber
```

## Components

### Frontend

React client and UI orchestration

- **Browser**: client · User-facing entry point
- [Routes](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Routes/appRoutes.js): routing · App route definitions · `frontend/src/Routes/appRoutes.js`
- [Private Route](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Components/privateRouter.jsx): auth guard · Authenticated route wrapper · `frontend/src/Components/privateRouter.jsx`
- [Auth Hook](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Hooks/userAuth.js): session state · Client auth/session state helper · `frontend/src/Hooks/userAuth.js`
- [API Services](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Services/api.js): http client · Backend API wrappers · `frontend/src/Services/api.js`
- [User Pages](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Pages/login.jsx): screens · Login, register, profile and dashboard views · `frontend/src/Pages/login.jsx`
- [Shared UI](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/frontend/src/Components/Sidebar.jsx): components · Reusable layout and controls · `frontend/src/Components/Sidebar.jsx`

### Backend

FastAPI service with layered architecture

- [FastAPI App](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/main.py): entrypoint · Backend application startup · `backend/src/cloud_storage_app/main.py`
- [API v1](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/presentation/api/v1/auth.py): presentation · HTTP routes for auth, users and health · `backend/src/cloud_storage_app/presentation/api/v1/auth.py`
- [Error Handler](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/presentation/middleware/error_handler.py): middleware · Centralized API error translation · `backend/src/cloud_storage_app/presentation/middleware/error_handler.py`
- [Use Cases](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/application/use_cases/user/create_user_use_case.py): application · User and auth workflows · `backend/src/cloud_storage_app/application/use_cases/user/create_user_use_case.py`
- [DTOs](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/application/dtos/user_dtos.py): contracts · Request and response data shapes · `backend/src/cloud_storage_app/application/dtos/user_dtos.py`
- [User Domain](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/domain/entities/user.py): domain · User entity, value objects and events · `backend/src/cloud_storage_app/domain/entities/user.py`
- [Repo Interface](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/domain/repositories/user_repository.py): domain port · User repository abstraction · `backend/src/cloud_storage_app/domain/repositories/user_repository.py`
- [Password Port](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/domain/services/password_service.py): domain service · Password hashing/verification contract · `backend/src/cloud_storage_app/domain/services/password_service.py`
- [DI Container](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/di/container.py): composition root · Wires interfaces to implementations · `backend/src/cloud_storage_app/infrastructure/di/container.py`
- [JWT & Crypto](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/auth/jwt_service.py): infrastructure · JWT auth and password hashing services · `backend/src/cloud_storage_app/infrastructure/auth/jwt_service.py`
- [DB Layer](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/infrastructure/database/connection.py): persistence · Connection, ORM models and repositories · `backend/src/cloud_storage_app/infrastructure/database/connection.py`
- [Object Storage](https://github.com/guilhermetorresm/cloud-storage-app/tree/main/backend/src/cloud_storage_app/infrastructure/storage): external storage · Planned S3-backed file storage boundary · `backend/src/cloud_storage_app/infrastructure/storage`
- [Auth Utils](https://github.com/guilhermetorresm/cloud-storage-app/blob/main/backend/src/cloud_storage_app/shared/auth_utils.py): shared · JWT helpers shared across layers · `backend/src/cloud_storage_app/shared/auth_utils.py`
- [Files Use Cases](https://github.com/guilhermetorresm/cloud-storage-app/tree/main/backend/src/cloud_storage_app/application/use_cases/files): planned application · Scaffold for file operations · `backend/src/cloud_storage_app/application/use_cases/files`

## Connections

- Browser → Routes: opens app · Browser enters the client application
- Routes → Private Route: protects · Routes send authenticated users through guard
- Private Route → Auth Hook: checks session · Auth guard relies on client session state
- Routes → User Pages: renders · Routes select page views
- User Pages → API Services: calls API · Pages use service wrappers for backend access
- User Pages → Shared UI: composes · Pages reuse shared UI components
- API Services → FastAPI App: requests · HTTP traffic goes to backend service
- FastAPI App → API v1: mounts · Main app exposes versioned API routes
- API v1 → Error Handler: handled by · Presentation layer centralizes errors
- API v1 → Use Cases: delegates · Routes invoke application workflows
- Use Cases → DTOs: uses · Use cases exchange DTOs with presentation
- Use Cases → User Domain: operates on · Business logic depends on domain entities and value objects
- Use Cases → Repo Interface: reads/writes · Use cases depend on repository abstraction
- Use Cases → Password Port: verifies passwords · Password contract keeps crypto out of workflows
- DI Container → API v1: injects · Composition root wires route dependencies
- DI Container → JWT & Crypto: binds · Container provides auth implementations
- DI Container → DB Layer: binds · Container provides persistence implementations
- JWT & Crypto → Auth Utils: shares · JWT helpers are reused across layers
- DB Layer → Repo Interface: implements · SQLAlchemy repository backs domain port
- DB Layer → User Domain: maps · ORM models persist the user aggregate
- Use Cases → Files Use Cases: extends to · File workflow scaffold sits beside user workflows
- Files Use Cases → Object Storage: targets · Planned external object storage boundary