# carl-joshua-fabregas/sp2_uppet_mobile_app architecture

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

- Interactive diagram: https://gitdiagram.com/carl-joshua-fabregas/sp2_uppet_mobile_app
- Repository: https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app

## Overview

UPPet is a two-part mobile system: an Expo/React Native client in `frontend/uppet` and a Node/Express backend in `backend`. The app is centered on peer-to-peer pet adoption for a specific locality, so the architecture is domain-heavy rather than generic CRUD-only.

1. **Client boundary**
   - The frontend is a mobile app built with Expo.
   - Navigation is organized with `app/` routes, including a drawer shell and tab-based sections for home, messages, my adoptees, and notifications.
   - Screen-level pages such as pet profiles, adopter profiles, application views, and chat screens sit alongside reusable UI cards and modals in `component/`.

2. **Frontend state and communication**
   - The app uses `axios` in `frontend/uppet/api/axios.js` to talk to the backend HTTP API.
   - Shared client state is split into contexts: `UserContext` for user/session data, `ChatContext` for chat state, and `SocketContext` for realtime connectivity.
   - This indicates a clear separation between navigation/UI, request logic, and cross-screen state.

3. **Backend structure**
   - The backend follows a layered Express pattern: `routes -> controllers -> services -> models`.
   - Routes expose domain endpoints, controllers handle request/response logic, services hold reusable business workflows, and models represent persistence objects.
   - This makes the backend easy to diagram as a set of domain modules rather than one monolithic API.

4. **Domain model boundaries**
   - Core entities include `Adopter`, `Pet`, `AdoptionApplication`, `Match`, `ChatThread`, `Messages`, `Notification`, and `Rating`.
   - These are separate subsystems with their own controllers and routes, which suggests the app supports the full adoption lifecycle: profile creation, pet listing, application submission, matching, messaging, notifications, and post-adoption feedback.

5. **Adoption workflow**
   - The main flow appears to be: an adopter creates a profile, a pet owner creates a pet profile, the adopter submits an adoption application, and a match is created when accepted.
   - Dedicated routes/controllers for adopters, pets, applications, and matches show that matching is a first-class business process, not just a simple listing/search feature.

6. **Messaging and realtime chat**
   - Chat is split into threads and messages, with both standard API controllers and service helpers.
   - The presence of `socket.js`, `SocketController.js`, and `socketMiddleware.js` strongly suggests realtime updates for chat and possibly notifications through Socket.IO or a similar websocket layer.
   - This is a key architectural boundary: HTTP for persistence/query, sockets for live delivery.

7. **Authentication and authorization**
   - `authController`, `authRouter`, and `authMiddleware` define the authentication boundary.
   - Protected routes likely gate profile edits, application actions, messaging, and owner-only operations.
   - The frontend’s user context likely mirrors authenticated identity/session state from the backend.

8. **Persistence and seed data**
   - The `models/` directory suggests a document-model ORM/ODM setup, likely backed by MongoDB through `database/config/database.js`.
   - The `database/` folder contains CSV seed files and `seed.js`, which implies the repo includes predefined demo data or initial dataset loading for adopters, pets, applications, chats, messages, notifications, and ratings.
   - This is useful for local setup and for diagramming initial data bootstrap separately from runtime traffic.

9. **Infrastructure and external services**
   - `backend/config/aws.js` indicates integration with AWS-backed services, likely for media or asset storage.
   - On the frontend, `app.json`, `eas.json`, and the README’s build instructions show the app is packaged and distributed through Expo EAS, with Android builds as the primary mobile deployment path.

10. **End-to-end data flow**
   - Typical request flow is: mobile screen action -> axios request -> backend route -> controller -> service/model -> database -> JSON response.
   - For live chat or presence-like updates, the flow shifts to socket connection -> socket middleware/controller -> message/thread processing -> broadcast to clients.
   - Notifications likely follow a similar pattern, combining persisted records with realtime delivery.

11. **What to draw as major subsystems**
   - A mobile client boundary with screens, reusable components, and contexts.
   - An API boundary with modular domain routes/controllers/services.
   - A persistence boundary with entity models and seeded dataset files.
   - A realtime boundary for chat/notifications.
   - An external storage/build boundary for AWS integration and Expo EAS mobile packaging.

Main entry points: [`backend/controller/SocketController.js`](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/controller/SocketController.js) (Socket bridge), [`backend/models`](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/models) (Domain models), [`frontend/uppet/app/index.jsx`](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/app/index.jsx) (Screens), [`backend/controller`](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/controller) (Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Mobile client"]
  node_app_shell["App shell<br/>expo navigation"]
  node_mobile_screens["Screens<br/>mobile views<br/>[index.jsx]"]
  node_ui_components["UI cards<br/>shared UI"]
  node_client_contexts(("Contexts<br/>client state"))
  node_http_client["API client<br/>axios transport<br/>[axios.js]"]
end

subgraph group_backend["Backend API"]
  node_routes["Routes<br/>express routers"]
  node_controllers["Controllers<br/>request handlers"]
  node_services["Services<br/>business workflows"]
  node_auth_boundary{{"Auth boundary<br/>security middleware<br/>[authMiddleware.js]"}}
end

subgraph group_realtime["Realtime layer"]
  node_socket_bridge(("Socket bridge<br/>realtime controller"))
  node_socket_config["Socket config<br/>realtime setup<br/>[socket.js]"]
  node_socket_middleware{{"Socket middleware<br/>realtime guard"}}
end

subgraph group_data["Data layer"]
  node_models[("Domain models<br/>persistence models")]
  node_db_config["DB config<br/>database setup<br/>[database.js]"]
  node_seed_data["Seed data<br/>bootstrap dataset<br/>[seed.js]"]
end

subgraph group_infra["Infrastructure"]
  node_aws_config["AWS config<br/>external storage<br/>[aws.js]"]
  node_expo_build["Expo build<br/>mobile packaging<br/>[eas.json]"]
end

node_app_shell -->|"navigates to"| node_mobile_screens
node_app_shell -->|"composes"| node_ui_components
node_mobile_screens -->|"requests via"| node_http_client
node_mobile_screens -->|"reads state"| node_client_contexts
node_ui_components -->|"updates state"| node_client_contexts
node_http_client -->|"calls"| node_routes
node_routes -->|"protects"| node_auth_boundary
node_routes -->|"dispatches to"| node_controllers
node_controllers -->|"delegates to"| node_services
node_controllers -->|"reads/writes"| node_models
node_services -->|"operates on"| node_models
node_models -->|"connects through"| node_db_config
node_seed_data -->|"loads"| node_models
node_socket_config -->|"initializes"| node_socket_bridge
node_socket_middleware -->|"guards"| node_socket_bridge
node_socket_bridge -->|"reuses"| node_services
node_socket_bridge -->|"broadcasts from"| node_models
node_controllers -.->|"notifies"| node_socket_bridge
node_mobile_screens -.->|"listens on"| node_socket_bridge
node_models -.->|"uses"| node_aws_config
node_app_shell -->|"packages with"| node_expo_build

click node_app_shell "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/frontend/uppet/app"
click node_mobile_screens "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/app/index.jsx"
click node_ui_components "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/frontend/uppet/component"
click node_client_contexts "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/frontend/uppet/context"
click node_http_client "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/api/axios.js"
click node_routes "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/routes"
click node_controllers "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/controller"
click node_services "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/services"
click node_auth_boundary "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/middleware/authMiddleware.js"
click node_socket_bridge "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/controller/SocketController.js"
click node_socket_config "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/config/socket.js"
click node_socket_middleware "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/middleware/socketMiddleware.js"
click node_models "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/models"
click node_db_config "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/config/database.js"
click node_seed_data "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/database/seed.js"
click node_aws_config "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/config/aws.js"
click node_expo_build "https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/eas.json"

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_app_shell,node_mobile_screens,node_ui_components,node_client_contexts,node_http_client toneBlue
class node_routes,node_controllers,node_services,node_auth_boundary toneAmber
class node_socket_bridge,node_socket_config,node_socket_middleware toneMint
class node_models,node_db_config,node_seed_data toneRose
class node_aws_config,node_expo_build toneIndigo
```

## Components

### Mobile client

Expo/React Native app and shared UI/state

- [App shell](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/frontend/uppet/app): expo navigation · Root Expo routes with drawer and tab navigation · `frontend/uppet/app`
- [Screens](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/app/index.jsx): mobile views · Profile, adoption, message, and gallery screens · `frontend/uppet/app/index.jsx`
- [UI cards](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/frontend/uppet/component): shared UI · Reusable cards, modals, and step-based creation flows · `frontend/uppet/component`
- [Contexts](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/frontend/uppet/context): client state · User, chat, and socket shared state · `frontend/uppet/context`
- [API client](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/api/axios.js): axios transport · HTTP bridge from the mobile app to the backend · `frontend/uppet/api/axios.js`

### Backend API

Express routes, controllers, services, and auth

- [Routes](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/routes): express routers · Domain route entrypoints for auth, pets, applications, chat, matches, messages, notifications, and ratings · `backend/routes`
- [Controllers](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/controller): request handlers · HTTP request/response handlers for each domain area · `backend/controller`
- [Services](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/services): business workflows · Reusable matching and messaging logic · `backend/services`
- [Auth boundary](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/middleware/authMiddleware.js): security middleware · Authentication and protected-route enforcement · `backend/middleware/authMiddleware.js`

### Realtime layer

Socket-driven chat and live updates

- [Socket bridge](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/controller/SocketController.js): realtime controller · Socket.IO-style connection handling for live updates · `backend/controller/SocketController.js`
- [Socket config](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/config/socket.js): realtime setup · Socket server wiring and middleware for connections · `backend/config/socket.js`
- [Socket middleware](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/middleware/socketMiddleware.js): realtime guard · Connection-time socket validation and attachment · `backend/middleware/socketMiddleware.js`

### Data layer

Models, database config, and seed data

- [Domain models](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/tree/master/backend/models): persistence models · Adopter, pet, application, match, chat, message, notification, and rating models · `backend/models`
- [DB config](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/config/database.js): database setup · Database connection and persistence initialization · `backend/config/database.js`
- [Seed data](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/database/seed.js): bootstrap dataset · CSV fixtures and seed loader for demo/local initialization · `database/seed.js`

### Infrastructure

External services and mobile build packaging

- [AWS config](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/backend/config/aws.js): external storage · Cloud storage integration for media or assets · `backend/config/aws.js`
- [Expo build](https://github.com/carl-joshua-fabregas/sp2_uppet_mobile_app/blob/master/frontend/uppet/eas.json): mobile packaging · EAS and Expo app packaging configuration · `frontend/uppet/eas.json`

## Connections

- App shell → Screens: navigates to · Drawer and tab routes open screen-level views
- App shell → UI cards: composes · Screens are built from shared cards, modals, and creation steps
- Screens → API client: requests via · User actions trigger HTTP calls through axios
- Screens → Contexts: reads state · Screens consume shared user, chat, and socket state
- UI cards → Contexts: updates state · Creation flows and cards interact with shared client state
- API client → Routes: calls · Mobile API requests enter the Express route layer
- Routes → Auth boundary: protects · Protected endpoints pass through authentication middleware
- Routes → Controllers: dispatches to · Routers hand requests to domain controllers
- Controllers → Services: delegates to · Controllers reuse workflow logic for matching and messaging
- Controllers → Domain models: reads/writes · Controllers persist and query domain records through models
- Services → Domain models: operates on · Business services coordinate across persistence models
- Domain models → DB config: connects through · Models are backed by the configured database connection
- Seed data → Domain models: loads · Seed scripts populate the domain entities
- Socket config → Socket bridge: initializes · Socket server setup connects the realtime controller
- Socket middleware → Socket bridge: guards · Socket connections pass through middleware before handling
- Socket bridge → Services: reuses · Realtime events can invoke message and matching workflows
- Socket bridge → Domain models: broadcasts from · Live events are driven by persisted chat and notification data
- Controllers → Socket bridge: notifies · HTTP actions may trigger live socket updates
- Screens → Socket bridge: listens on · Chat and notification screens receive realtime updates
- Domain models → AWS config: uses · Domain data may reference cloud-backed assets
- App shell → Expo build: packages with · The mobile client is built and distributed through Expo EAS
