How sushanttx/fullstack-filestorage works
1. Overall shape
This repo is a full-stack application with a Spring Boot backend and two frontend implementations: React and Angular. The backend is the system of record; the frontends are alternative clients that call the same REST API.
2. Core domain
The main business domain is customer management with profile image storage. The README describes the product as a file storage app, but the code strongly centers on customers, authentication, and customer profile pictures. Customer records live in the database, while image blobs are handled separately through the storage layer.
3. Backend entry points
The backend is a single Spring Boot service under backend/. Main API surfaces are:
• AuthenticationController for login/token issuance
• CustomerController for customer CRUD and related operations
• PingPongController for health/demo-style reachability
This is not a microservices repo in code structure; it is a modular monolith with clear package boundaries.
4. Request flow
A typical request path is:
Browser/UI → REST endpoint → service layer → data access / storage → PostgreSQL and/or S3 → response DTO.
The backend uses DTOs and mapping classes to avoid exposing persistence entities directly to the clients.
5. Authentication and authorization
Security is JWT-based:
• AuthenticationService authenticates credentials
• JWTUtil creates/parses tokens
• JWTAuthenticationFilter protects requests
• SecurityConfig / SecurityFilterChainConfig define access rules
• DelegatedAuthEntryPoint and exception handlers shape unauthorized/error responses
The frontend stores and forwards the token via its client-side auth plumbing.
6. Customer subsystem
The customer package contains the main business workflow:
• CustomerService orchestrates registration, updates, and retrieval
• CustomerDao abstracts persistence
• Multiple DAO implementations exist: JDBC, JPA, and in-memory list (CustomerJDBCDataAccessService, CustomerJPADataAccessService, CustomerListDataAccessService)
• CustomerRepository supports the JPA path
• CustomerDTOMapper converts entity → API model
This abstraction suggests the repository is teaching or comparing persistence strategies, not just using one fixed repository pattern.
7. Storage subsystem
The s3 package indicates a separate storage boundary for profile images/files:
• S3Service encapsulates object storage operations
• S3Config / S3Buckets hold configuration
• FakeS3 exists for local/test substitution
The backend likely stores image metadata with the customer row and the file itself in S3-compatible storage.
8. Database and schema management
Persistence is backed by PostgreSQL. Schema evolution is managed with Flyway migrations in backend/src/main/resources/db/migration:
• initial setup
• later addition of a customer profile image column/structure
This means the backend expects a relational database as the canonical store for users/customers and auth-related data.
9. Frontend boundaries
There are two client apps:
• React in frontend/react
• Angular in frontend/angular
Both have their own components, auth services, customer services, route protection/guards, and environment configuration. The React app also has a context-based auth layer and protected routes. In the architecture diagram, treat them as separate presentation-layer options rather than one combined UI.
10. UI-to-API interaction
The frontends model the same backend contracts:
• authentication request/response
• customer registration/update DTOs
• customer DTOs
They each handle login, signup, customer browsing, create/update flows, and token-based API calls. The backend remains stateless from the UI’s perspective except for JWT handling.
11. Validation and error handling
The backend has dedicated exception types and a global handler:
• DuplicateResourceException
• ResourceNotFoundException
• RequestValidationException
• DefaultExceptionHandler
• ApiError
This keeps the API responses consistent and gives the frontends predictable failure modes for form validation and authorization errors.
12. Infrastructure and deployment
The repo is container-first:
• backend and frontend Dockerfiles
• docker-compose.yml for local orchestration
• nginx.conf for reverse proxy behavior
• Dockerrun.aws.json and CI/CD workflows for AWS Elastic Beanstalk-style deployment
The deployment boundary is therefore: containerized frontend(s) + containerized Spring Boot API + PostgreSQL.
13. Testing and verification
The backend has a strong test split:
• unit tests for customer services and mappers
• integration tests with Testcontainers
• journey tests for authentication and customer flows
This suggests the system’s important contract boundaries are API behavior, persistence behavior, and storage behavior, not just isolated methods.
14. What to draw in an architecture diagram
The key diagram boxes should be:
• browser/client UI
• React frontend
• Angular frontend
• Spring Boot backend
• JWT/security layer
• customer service + DAO/repository layer
• S3/object storage
• PostgreSQL
• CI/CD + container/deployment layer
The main arrows are authenticated REST calls from the UI to backend, and backend writes/reads to PostgreSQL plus S3 for image assets.
Main entry points: Main.java Spring API · docker-compose.yml Deploy Stack · CustomerService.java Customer Service · CustomerDao.java Customer DAO
Components 18
Presentation
Alternative client applications that call the same backend API.
- Browser · End-user entry point for either frontend.
- React App · React client with auth context and protected routes.
frontend/react/src/main.jsx - Angular App · Angular client with route guards, services, and interceptors.
frontend/angular/src/main.ts
Backend
Spring Boot modular monolith exposing authentication and customer APIs.
- Spring API · Single Spring Boot application entry point.
backend/src/main/java/com/sushant/Main.java - Auth API · Login and token issuance endpoints.
backend/src/main/java/com/sushant/auth/AuthenticationController.java - Customer API · Customer CRUD and profile-image endpoints.
backend/src/main/java/com/sushant/customer/CustomerController.java - Security · Request filtering and access rules for protected endpoints.
backend/src/main/java/com/sushant/security/SecurityConfig.java - JWT Layer · Token creation, parsing, and authentication filter.
backend/src/main/java/com/sushant/jwt/JWTUtil.java - Auth Service · Validates credentials and issues auth responses.
backend/src/main/java/com/sushant/auth/AuthenticationService.java - Customer Service · Coordinates customer registration, update, and lookup workflows.
backend/src/main/java/com/sushant/customer/CustomerService.java - Customer DAO · Persistence boundary with JDBC, JPA, and in-memory implementations.
backend/src/main/java/com/sushant/customer/CustomerDao.java - JPA Repo · Spring Data repository backing the JPA path.
backend/src/main/java/com/sushant/customer/CustomerRepository.java - DTO Mapper · Maps customer entities to API DTOs.
backend/src/main/java/com/sushant/customer/CustomerDTOMapper.java - S3 Storage · Encapsulates profile image and file-object storage.
backend/src/main/java/com/sushant/s3/S3Service.java - Errors · Global exception handling and API error responses.
backend/src/main/java/com/sushant/exception/DefaultExceptionHandler.java
Infrastructure
Database, storage, schema migration, and deployment concerns.
- PostgreSQL · Primary relational store for customers and auth-related data.
- Migrations · Database schema setup and profile-image migration scripts.
backend/src/main/resources/db/migration/V1__Initial_Setup.sql - Deploy Stack · Docker, compose, nginx, and AWS deployment wiring.
docker-compose.yml
Connections 22
- Browser → React App: uses · Browser loads the React client.
- Browser → Angular App: uses · Browser loads the Angular client.
- React App → Spring API: REST · React calls the shared backend API.
- Angular App → Spring API: REST · Angular calls the shared backend API.
- Spring API → Security: protects · Backend request handling is gated by Spring Security.
- Security → JWT Layer: uses · Security configuration relies on JWT filtering and token utilities.
- Spring API → Auth API: routes · Authentication endpoints are exposed by the backend.
- Auth API → Auth Service: delegates · Controller delegates login/token work to the service layer.
- Spring API → Customer API: routes · Customer endpoints are exposed by the backend.
- Customer API → Customer Service: delegates · Controller delegates customer workflows to the service layer.
- Customer Service → Customer DAO: persists via · Customer service uses the DAO abstraction.
- Customer DAO → JPA Repo: jpa path · One persistence path goes through Spring Data JPA.
- Customer Service → DTO Mapper: maps · Service/API boundary uses DTO mapping for responses.
- Customer Service → S3 Storage: stores images · Customer profile images are managed through object storage.
- Customer DAO → PostgreSQL: reads/writes · Customer data is stored in PostgreSQL.
- Migrations → PostgreSQL: migrates · Flyway evolves the database schema.
- Spring API → Migrations: loads schema · Backend startup expects migrated relational schema.
- Spring API → Errors: formats errors · Exceptions are converted to consistent API responses.
- Deploy Stack → Spring API: runs · Container and deployment layer packages the backend service.
- Deploy Stack → React App: runs · Container and deployment layer packages the React client.
- Deploy Stack → Angular App: runs · Container and deployment layer can package the Angular client.
- Deploy Stack → PostgreSQL: depends on · Local and deployed stacks depend on PostgreSQL.