# diksha78dev/familyvault architecture

> Architecture diagram of the GitHub repository diksha78dev/familyvault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/diksha78dev/familyvault
- Repository: https://github.com/diksha78dev/familyvault

## Overview

1. **Repository shape**
   - This is a monorepo with two distinct deployable parts:
     - a **Spring Boot backend** at the repository root
     - a **React frontend** in `familyvault-frontend/`
   - The architecture is a classic client/server split, with the frontend consuming backend APIs over HTTP.

2. **Product boundary**
   - FamilyVault is a document vault for family groups.
   - Core user flows are: **join a family group with a code**, **upload documents**, and **search/list documents by name or category**.
   - The app is designed for browser use on mobile, so there is no native mobile client or desktop app layer.

3. **Backend application entry**
   - The backend starts from `FamilyVaultApplication.java`, which is the Spring Boot bootstrap class.
   - Maven is the build/runtime tool for the server side (`pom.xml`, `mvnw`), so the backend is the authoritative application runtime.

4. **Backend domain model**
   - There are two main domain objects:
     - `Document` — represents uploaded files and their metadata
     - `FamilyGroup` — represents a family workspace or access group
   - These two entities define the business boundary: documents belong to a family context rather than to a generic global library.

5. **Backend API layer**
   - `DocumentController.java` and `FamilyGroupController.java` expose the HTTP endpoints for the app.
   - These controllers are the integration point between the React UI and the server-side business logic.
   - Based on the README, this API likely supports document creation/upload, listing, search, and family-group joining/lookup.

6. **Backend business logic**
   - `DocumentService.java` and `FamilyGroupService.java` hold the application rules and orchestration.
   - This service layer sits between controllers and persistence/storage, which keeps the controllers thin and makes the document/group workflows explicit.

7. **Persistence layer**
   - `DocumentRepository.java` and `FamilyGroupRepository.java` are the JPA repositories.
   - The README states the backend uses **Spring Boot + JPA + MySQL**, so relational persistence is the system-of-record for document metadata and family-group data.
   - `application.properties.example` indicates runtime configuration is externalized, likely including database settings and other environment-specific values.

8. **File/storage integration**
   - `CloudinaryConfig.java` is a notable architectural boundary: document files are not just stored in the database.
   - This implies uploaded document content is handled through an external file/media service, while the database stores metadata and references.
   - In the architecture diagram, Cloudinary should be shown as a separate external dependency from MySQL.

9. **Frontend structure**
   - The React app is organized around a few clear UI concerns:
     - `LandingPage.js` for the public entry experience
     - `LoginPage.js` for group-code access
     - `UploadForm.js` for submitting documents
     - `DocumentList.js` for browsing/searching documents
     - `ProtectedRoute.js` for route gating on the client side
   - `App.js` is the main composition/routing layer, with shared styling in `App.css` and `index.css`.

10. **Frontend-to-backend data flow**
   - The expected flow is:
     1. user opens the React app
     2. user joins or accesses a family group
     3. protected views let the user upload or browse documents
     4. the frontend sends API requests to the Spring Boot backend
     5. the backend persists metadata in MySQL and coordinates file storage through Cloudinary
   - This means the React app is a presentation/orchestration layer; it does not own business state.

11. **Security/access boundary**
   - The app avoids “complex signup” and instead uses a **simple family code** model.
   - `ProtectedRoute.js` suggests client-side route protection, but the real access model is still centered on the backend’s family-group logic.
   - For an architecture diagram, treat “family code membership” as the main authorization boundary.

12. **Deployment and packaging**
   - Frontend deployment is configured separately via `familyvault-frontend/vercel.json`, so the UI can be hosted independently from the backend.
   - The repository therefore supports a split deployment model: static React hosting plus a Spring Boot API server.
   - The `public/` assets and `manifest.json` confirm the frontend is a browser-first app.

13. **Testing and quality boundaries**
   - Backend testing exists via `src/test/.../FamilyVaultApplicationTests.java`.
   - The React app also has test scaffolding (`App.test.js`, `setupTests.js`).
   - This suggests both layers are testable independently, reinforcing the separation between UI and server logic.

Main entry points: [`src/main/java/com/diksha/FamilyVault/DocumentService.java`](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentService.java) (Doc service), [`src/main/java/com/diksha/FamilyVault/DocumentController.java`](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentController.java) (Docs API), [`familyvault-frontend/src/App.js`](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/App.js) (App shell), [`src/main/java/com/diksha/FamilyVault/FamilyGroupService.java`](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupService.java) (Group service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_app(("FamilyVaultApp<br/>spring boot entrypoint"))
  node_doc_controller["Docs API<br/>REST controller"]
  node_group_controller["Groups API<br/>REST controller"]
  node_doc_service["Doc service<br/>application service"]
  node_group_service["Group service<br/>application service"]
  node_doc_repo["Doc repo<br/>jpa repository"]
  node_group_repo["Group repo<br/>jpa repository"]
  node_document_entity["Document<br/>domain entity<br/>[Document.java]"]
  node_family_group_entity["FamilyGroup<br/>domain entity<br/>[FamilyGroup.java]"]
  node_cloudinary_config["Cloudinary<br/>storage config"]
end

subgraph group_frontend["Frontend"]
  node_app_root["App shell<br/>react app<br/>[App.js]"]
  node_landing_page["Landing<br/>react page<br/>[LandingPage.js]"]
  node_login_page["Join group<br/>react page<br/>[LoginPage.js]"]
  node_protected_route["Protected route<br/>react guard<br/>[ProtectedRoute.js]"]
  node_upload_form["Upload form<br/>react component<br/>[UploadForm.js]"]
  node_document_list["Document list<br/>react component<br/>[DocumentList.js]"]
end

subgraph group_external["External systems"]
  node_mysql[("MySQL<br/>relational database")]
  node_cloudinary[("Cloudinary service<br/>external storage")]
end

node_backend_app -->|"exposes"| node_doc_controller
node_backend_app -->|"exposes"| node_group_controller
node_doc_controller -->|"calls"| node_doc_service
node_group_controller -->|"calls"| node_group_service
node_doc_service -->|"persists via"| node_doc_repo
node_group_service -->|"persists via"| node_group_repo
node_doc_service -->|"uses"| node_document_entity
node_group_service -->|"uses"| node_family_group_entity
node_doc_repo -->|"reads/writes"| node_mysql
node_group_repo -->|"reads/writes"| node_mysql
node_doc_service -->|"uploads via"| node_cloudinary_config
node_cloudinary_config -->|"integrates with"| node_cloudinary
node_app_root -->|"navigates to"| node_landing_page
node_app_root -->|"navigates to"| node_login_page
node_app_root -->|"guards"| node_protected_route
node_protected_route -->|"allows"| node_upload_form
node_protected_route -->|"allows"| node_document_list
node_upload_form -->|"posts to"| node_doc_controller
node_document_list -->|"queries"| node_doc_controller
node_login_page -->|"joins via"| node_group_controller

click node_backend_app "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyVaultApplication.java"
click node_doc_controller "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentController.java"
click node_group_controller "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupController.java"
click node_doc_service "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentService.java"
click node_group_service "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupService.java"
click node_doc_repo "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentRepository.java"
click node_group_repo "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupRepository.java"
click node_document_entity "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/Document.java"
click node_family_group_entity "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroup.java"
click node_cloudinary_config "https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/CloudinaryConfig.java"
click node_app_root "https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/App.js"
click node_landing_page "https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/LandingPage.js"
click node_login_page "https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/LoginPage.js"
click node_protected_route "https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/ProtectedRoute.js"
click node_upload_form "https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/UploadForm.js"
click node_document_list "https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/DocumentList.js"

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_backend_app,node_doc_controller,node_group_controller,node_doc_service,node_group_service,node_doc_repo,node_group_repo,node_document_entity,node_family_group_entity,node_cloudinary_config toneBlue
class node_app_root,node_landing_page,node_login_page,node_protected_route,node_upload_form,node_document_list toneAmber
class node_mysql,node_cloudinary toneMint
```

## Components

### Backend

Spring Boot API, domain, persistence, and file-storage integration.

- [FamilyVaultApp](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyVaultApplication.java): spring boot entrypoint · Bootstraps the Spring Boot server. · `src/main/java/com/diksha/FamilyVault/FamilyVaultApplication.java`
- [Docs API](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentController.java): REST controller · HTTP endpoints for document workflows. · `src/main/java/com/diksha/FamilyVault/DocumentController.java`
- [Groups API](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupController.java): REST controller · HTTP endpoints for family-group access and lookup. · `src/main/java/com/diksha/FamilyVault/FamilyGroupController.java`
- [Doc service](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentService.java): application service · Orchestrates upload, listing, and search rules for documents. · `src/main/java/com/diksha/FamilyVault/DocumentService.java`
- [Group service](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupService.java): application service · Handles family-code membership and group workflows. · `src/main/java/com/diksha/FamilyVault/FamilyGroupService.java`
- [Doc repo](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/DocumentRepository.java): jpa repository · Persists and queries document metadata. · `src/main/java/com/diksha/FamilyVault/DocumentRepository.java`
- [Group repo](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroupRepository.java): jpa repository · Persists and queries family-group records. · `src/main/java/com/diksha/FamilyVault/FamilyGroupRepository.java`
- [Document](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/Document.java): domain entity · Uploaded file metadata and family context. · `src/main/java/com/diksha/FamilyVault/Document.java`
- [FamilyGroup](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/FamilyGroup.java): domain entity · Family workspace and access group. · `src/main/java/com/diksha/FamilyVault/FamilyGroup.java`
- [Cloudinary](https://github.com/diksha78dev/familyvault/blob/main/src/main/java/com/diksha/FamilyVault/CloudinaryConfig.java): storage config · Configures external document/file media handling. · `src/main/java/com/diksha/FamilyVault/CloudinaryConfig.java`

### Frontend

React browser app for joining groups, uploading, and browsing documents.

- [App shell](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/App.js): react app · Main React composition and routing layer. · `familyvault-frontend/src/App.js`
- [Landing](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/LandingPage.js): react page · Public entry experience. · `familyvault-frontend/src/LandingPage.js`
- [Join group](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/LoginPage.js): react page · Family-code access and group entry flow. · `familyvault-frontend/src/LoginPage.js`
- [Protected route](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/ProtectedRoute.js): react guard · Client-side route gating for authenticated family access. · `familyvault-frontend/src/ProtectedRoute.js`
- [Upload form](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/UploadForm.js): react component · Document submission UI. · `familyvault-frontend/src/UploadForm.js`
- [Document list](https://github.com/diksha78dev/familyvault/blob/main/familyvault-frontend/src/DocumentList.js): react component · Browsing and search UI for documents. · `familyvault-frontend/src/DocumentList.js`

### External systems

Runtime dependencies outside the repository.

- **MySQL**: relational database · System of record for document metadata and family-group data.
- **Cloudinary service**: external storage · External file/media storage for uploaded documents.

## Connections

- FamilyVaultApp → Docs API: exposes · Starts the API runtime that serves document endpoints.
- FamilyVaultApp → Groups API: exposes · Starts the API runtime that serves group endpoints.
- Docs API → Doc service: calls · Delegates document operations to application logic.
- Groups API → Group service: calls · Delegates family-group operations to application logic.
- Doc service → Doc repo: persists via · Stores and queries document metadata.
- Group service → Group repo: persists via · Stores and queries family-group records.
- Doc service → Document: uses · Manipulates document domain objects.
- Group service → FamilyGroup: uses · Manipulates family-group domain objects.
- Doc repo → MySQL: reads/writes · JPA persistence target for document data.
- Group repo → MySQL: reads/writes · JPA persistence target for group data.
- Doc service → Cloudinary: uploads via · Coordinates file handling through external media storage.
- Cloudinary → Cloudinary service: integrates with · Connects the backend to Cloudinary.
- App shell → Landing: navigates to · Composes the public landing experience.
- App shell → Join group: navigates to · Composes the family-code access flow.
- App shell → Protected route: guards · Wraps protected views with client-side access checks.
- Protected route → Upload form: allows · Shows upload flow after group access.
- Protected route → Document list: allows · Shows document browsing after group access.
- Upload form → Docs API: posts to · Sends upload requests to the backend API.
- Document list → Docs API: queries · Fetches document lists and search results from the backend API.
- Join group → Groups API: joins via · Uses group endpoints for family-code access.
