# vandilsonbrito/find-a-friend architecture

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

- Interactive diagram: https://gitdiagram.com/vandilsonbrito/find-a-friend
- Repository: https://github.com/vandilsonbrito/find-a-friend

## Overview

Find A Friend connects animal-welfare organizations with prospective pet adopters. The user workflow is to browse and filter available pets by city and characteristics, view a pet’s details, then contact its organization directly via WhatsApp; organizations register, authenticate, and manage pet listings and profiles. The backend exposes these capabilities through Fastify routes, with repository-backed persistence and Cloudinary image uploads. Edges reflect the sampled routing and client calls or README-described behavior; some controller-to-use-case links are not shown in the excerpts.

Main entry points: [`frontend/src/App.tsx`](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/App.tsx) (Web application), [`backend/src/app.ts`](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/app.ts) (Fastify API), [`backend/src/http/controllers/pets/routes.ts`](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/pets/routes.ts) (Pet routes), [`backend/src/http/controllers/orgs/routes.ts`](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/orgs/routes.ts) (Organization routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Adopter and organization web app"]
  node_webapp["Web application<br/>[App.tsx]"]
  node_petbrowse["Pet browsing<br/>[Pets.tsx]"]
  node_petdetail["Pet details<br/>[PetDetails.tsx]"]
  node_orgbrowse["Organization directory<br/>[Organizations.tsx]"]
  node_dashboard["Organization dashboard<br/>[Dashboard.tsx]"]
  node_signup["Organization signup<br/>[SignUp.tsx]"]
  node_httpclient["HTTP client<br/>[index.ts]"]
  node_petquery["Available-pet query"]
end

subgraph group_api["API and domain operations"]
  node_api["Fastify API<br/>[app.ts]"]
  node_petroutes["Pet routes<br/>[routes.ts]"]
  node_orgroutes["Organization routes<br/>[routes.ts]"]
  node_authroutes["Auth routes<br/>[routes.ts]"]
  node_petoperations["Pet operations"]
  node_orgoperations["Organization operations"]
end

subgraph group_data["Persistence and media"]
  node_petrepo["Pet repository"]
  node_orgrepo["Organization repository"]
  node_database[("PostgreSQL database")]
  node_imagestore["Cloudinary image storage"]
end

subgraph group_auth["Authentication"]
  node_authstate["Session state<br/>[AuthProvider.tsx]"]
  node_jwt["JWT verification<br/>[verify-jwt.ts]"]
end

node_adopter(("Prospective adopter"))
node_orguser(("Organization user"))

node_adopter -->|"browses pets"| node_petbrowse
node_petbrowse -->|"loads filters"| node_petquery
node_petquery -->|"requests pets"| node_httpclient
node_httpclient -.->|"calls API"| node_api
node_adopter -->|"views details"| node_petdetail
node_petdetail -.->|"contacts organization"| node_orgbrowse
node_orguser -->|"registers"| node_signup
node_orguser -->|"manages listings"| node_dashboard
node_webapp -->|"provides session"| node_authstate
node_webapp -->|"routes to"| node_petbrowse
node_webapp -->|"routes to"| node_petdetail
node_webapp -->|"routes to"| node_orgbrowse
node_webapp -->|"protects route"| node_dashboard
node_api -->|"registers routes"| node_petroutes
node_api -->|"registers routes"| node_orgroutes
node_api -->|"registers routes"| node_authroutes
node_petroutes -->|"guards mutations"| node_jwt
node_orgroutes -->|"guards profile routes"| node_jwt
node_authroutes -->|"guards logout"| node_jwt
node_petroutes -.->|"dispatches operations"| node_petoperations
node_orgroutes -.->|"dispatches operations"| node_orgoperations
node_petoperations -.->|"uses repository"| node_petrepo
node_orgoperations -.->|"uses repository"| node_orgrepo
node_petrepo -->|"reads and writes"| node_database
node_orgrepo -.->|"persists organizations"| node_database
node_petoperations -.->|"uploads pet photos"| node_imagestore

click node_webapp "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/App.tsx"
click node_petbrowse "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/Pets.tsx"
click node_petdetail "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/PetDetails.tsx"
click node_orgbrowse "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/Organizations.tsx"
click node_dashboard "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/Dashboard.tsx"
click node_signup "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/SignUp.tsx"
click node_authstate "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/context/AuthProvider.tsx"
click node_httpclient "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/axios/index.ts"
click node_petquery "https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/services/hooks/useGetAvailablePets.ts"
click node_api "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/app.ts"
click node_petroutes "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/pets/routes.ts"
click node_orgroutes "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/orgs/routes.ts"
click node_authroutes "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/auth/routes.ts"
click node_petoperations "https://github.com/vandilsonbrito/find-a-friend/tree/main/backend/src/use-cases/pets"
click node_orgoperations "https://github.com/vandilsonbrito/find-a-friend/tree/main/backend/src/use-cases/orgs"
click node_jwt "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/middlewares/verify-jwt.ts"
click node_petrepo "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/repositories/prisma/prisma-pets-repository.ts"
click node_orgrepo "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/repositories/prisma/prisma-orgs-repository.ts"
click node_imagestore "https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/services/cloudinary-storage.ts"

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_webapp,node_petbrowse,node_petdetail,node_orgbrowse,node_dashboard,node_signup,node_httpclient,node_petquery,node_orguser toneBlue
class node_api,node_petroutes,node_orgroutes,node_authroutes,node_petoperations,node_orgoperations toneAmber
class node_petrepo,node_orgrepo,node_database,node_imagestore toneMint
class node_authstate,node_jwt toneRose
class node_adopter toneIndigo
```

## Components

### Adopter and organization web app

- [Web application](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Pet browsing](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/Pets.tsx): `frontend/src/pages/Pets.tsx`
- [Pet details](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/PetDetails.tsx): `frontend/src/pages/PetDetails.tsx`
- [Organization directory](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/Organizations.tsx): `frontend/src/pages/Organizations.tsx`
- [Organization dashboard](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/Dashboard.tsx): `frontend/src/pages/Dashboard.tsx`
- [Organization signup](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/pages/SignUp.tsx): `frontend/src/pages/SignUp.tsx`
- [HTTP client](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/axios/index.ts): `frontend/src/axios/index.ts`
- [Available-pet query](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/services/hooks/useGetAvailablePets.ts): `frontend/src/services/hooks/useGetAvailablePets.ts`

### API and domain operations

- [Fastify API](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [Pet routes](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/pets/routes.ts): `backend/src/http/controllers/pets/routes.ts`
- [Organization routes](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/orgs/routes.ts): `backend/src/http/controllers/orgs/routes.ts`
- [Auth routes](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/controllers/auth/routes.ts): `backend/src/http/controllers/auth/routes.ts`
- [Pet operations](https://github.com/vandilsonbrito/find-a-friend/tree/main/backend/src/use-cases/pets): `backend/src/use-cases/pets`
- [Organization operations](https://github.com/vandilsonbrito/find-a-friend/tree/main/backend/src/use-cases/orgs): `backend/src/use-cases/orgs`

### Persistence and media

- [Pet repository](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/repositories/prisma/prisma-pets-repository.ts): `backend/src/repositories/prisma/prisma-pets-repository.ts`
- [Organization repository](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/repositories/prisma/prisma-orgs-repository.ts): `backend/src/repositories/prisma/prisma-orgs-repository.ts`
- **PostgreSQL database**
- [Cloudinary image storage](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/services/cloudinary-storage.ts): `backend/src/services/cloudinary-storage.ts`

### Authentication

- [Session state](https://github.com/vandilsonbrito/find-a-friend/blob/main/frontend/src/context/AuthProvider.tsx): `frontend/src/context/AuthProvider.tsx`
- [JWT verification](https://github.com/vandilsonbrito/find-a-friend/blob/main/backend/src/http/middlewares/verify-jwt.ts): `backend/src/http/middlewares/verify-jwt.ts`

### Other components

- **Prospective adopter**
- **Organization user**

## Connections

- Prospective adopter → Pet browsing: browses pets
- Pet browsing → Available-pet query: loads filters (evidence: `frontend/src/pages/Pets.tsx`)
- Available-pet query → HTTP client: requests pets (evidence: `frontend/src/services/hooks/useGetAvailablePets.ts`)
- HTTP client → Fastify API: calls API
- Prospective adopter → Pet details: views details
- Pet details → Organization directory: contacts organization
- Organization user → Organization signup: registers
- Organization user → Organization dashboard: manages listings
- Web application → Session state: provides session (evidence: `frontend/src/App.tsx`)
- Web application → Pet browsing: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Pet details: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Organization directory: routes to (evidence: `frontend/src/App.tsx`)
- Web application → Organization dashboard: protects route (evidence: `frontend/src/App.tsx`)
- Fastify API → Pet routes: registers routes (evidence: `backend/src/app.ts`)
- Fastify API → Organization routes: registers routes (evidence: `backend/src/app.ts`)
- Fastify API → Auth routes: registers routes (evidence: `backend/src/app.ts`)
- Pet routes → JWT verification: guards mutations (evidence: `backend/src/http/controllers/pets/routes.ts`)
- Organization routes → JWT verification: guards profile routes (evidence: `backend/src/http/controllers/orgs/routes.ts`)
- Auth routes → JWT verification: guards logout (evidence: `backend/src/http/controllers/auth/routes.ts`)
- Pet routes → Pet operations: dispatches operations
- Organization routes → Organization operations: dispatches operations
- Pet operations → Pet repository: uses repository
- Organization operations → Organization repository: uses repository
- Pet repository → PostgreSQL database: reads and writes (evidence: `backend/src/repositories/prisma/prisma-pets-repository.ts`)
- Organization repository → PostgreSQL database: persists organizations
- Pet operations → Cloudinary image storage: uploads pet photos
