How guilhermetorresm/cloud-storage-app works
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: create_user_use_case.py Use Cases · auth.py API v1 · container.py DI Container · appRoutes.js Routes
Components 21
Frontend
React client and UI orchestration
- Browser · User-facing entry point
- Routes · App route definitions
frontend/src/Routes/appRoutes.js - Private Route · Authenticated route wrapper
frontend/src/Components/privateRouter.jsx - Auth Hook · Client auth/session state helper
frontend/src/Hooks/userAuth.js - API Services · Backend API wrappers
frontend/src/Services/api.js - User Pages · Login, register, profile and dashboard views
frontend/src/Pages/login.jsx - Shared UI · Reusable layout and controls
frontend/src/Components/Sidebar.jsx
Backend
FastAPI service with layered architecture
- FastAPI App · Backend application startup
backend/src/cloud_storage_app/main.py - API v1 · HTTP routes for auth, users and health
backend/src/cloud_storage_app/presentation/api/v1/auth.py - Error Handler · Centralized API error translation
backend/src/cloud_storage_app/presentation/middleware/error_handler.py - Use Cases · User and auth workflows
backend/src/cloud_storage_app/application/use_cases/user/create_user_use_case.py - DTOs · Request and response data shapes
backend/src/cloud_storage_app/application/dtos/user_dtos.py - User Domain · User entity, value objects and events
backend/src/cloud_storage_app/domain/entities/user.py - Repo Interface · User repository abstraction
backend/src/cloud_storage_app/domain/repositories/user_repository.py - Password Port · Password hashing/verification contract
backend/src/cloud_storage_app/domain/services/password_service.py - DI Container · Wires interfaces to implementations
backend/src/cloud_storage_app/infrastructure/di/container.py - JWT & Crypto · JWT auth and password hashing services
backend/src/cloud_storage_app/infrastructure/auth/jwt_service.py - DB Layer · Connection, ORM models and repositories
backend/src/cloud_storage_app/infrastructure/database/connection.py - Object Storage · Planned S3-backed file storage boundary
backend/src/cloud_storage_app/infrastructure/storage - Auth Utils · JWT helpers shared across layers
backend/src/cloud_storage_app/shared/auth_utils.py - Files Use Cases · Scaffold for file operations
backend/src/cloud_storage_app/application/use_cases/files
Connections 22
- 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