# fliotta/puppysignal architecture

> Architecture diagram of the GitHub repository fliotta/puppysignal, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fliotta/puppysignal
- Repository: https://github.com/fliotta/puppysignal

## Overview

##### Main Components Identification

The system consists of three main components:
- Backend (FastAPI-based REST API)
- Mobile Application (React Native)
- Web Application (Found Page)
- Database (SQL-based, indicated by Alembic migrations)

##### Detailed Architecture Breakdown

A. Backend Layer:
- Authentication Service (auth.py)
- Pet Management Service (pet.py)
- Notification Service (notification.py)
- Profile Management (profile.py)
- QR Code Scanning Service (scan.py)
- Data Service (data.py)

B. Database Layer:
- Database with main entities:
- Users
- Pets
- Locations
- Notifications
- FCM Tokens
- Breeds/Species

C. Mobile Application Layer:
- React Native app with main features:
- Authentication Views
- Pet Management
- Profile Management
- Location Tracking
- Push Notifications

D. Web Application Layer:
- Found Page component for QR code scanning

**┌─────────────────────────────────────────────┐**
- Client Layer                 │
- ┐ ┌─────────────────────┐│
- Mobile App       │ │     Web App         ││
- (React Native)   │ │     (Found Page)    ││
- ┘ └─────────────────────┘│
- ↕                    ↕             │
**┌─────────────────────────────────────────────┐**
- API Layer                     │
- ┤
- FastAPI Backend               │
- ┌─────────┐ ┌─────────┐ ┌──────────┐     │
- Auth   │ │  Pets   │ │ Notif.   │     │
- ┘ └─────────┘ └──────────┘     │
- ┘
- ↕
**┌─────────────────────────────────────────────┐**
- Database Layer                  │
- ┘

##### Important Flows to Highlight
- QR Code scanning flow
- Push notification flow
- Authentication flow
- Location tracking flow

##### Additional Elements
- External service integrations (Firebase Cloud Messaging)
- Security layers (authentication/authorization)

##### Technical Details
- REST API endpoints grouping
- Database relationships
- Mobile app navigation structure
- Environment configurations

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client["Client Layer"]
        direction TB
        subgraph MobileApp["Mobile Application"]
            direction TB
            AuthView["Authentication View"]:::mobile
            PetView["Pet Management"]:::mobile
            ProfileView["Profile Management"]:::mobile
            LocationView["Location Tracking"]:::mobile
            PetCreation["Pet Creation"]:::mobile
            MobileAPI["Mobile API Services"]:::mobile
        end

        subgraph WebApp["Web Application"]
            direction TB
            FoundPage["Found Page"]:::web
            PetServices["Pet Services"]:::web
        end
    end

    subgraph Backend["Backend Layer"]
        direction TB
        subgraph API["FastAPI Services"]
            direction TB
            Auth["Authentication Service"]:::api
            PetMgmt["Pet Management"]:::api
            NotifService["Notification Service"]:::api
            ProfileMgmt["Profile Management"]:::api
            ScanService["QR Code Scanning"]:::api
            DataService["Data Service"]:::api
        end

        subgraph Config["Configuration"]
            direction TB
            BackendConfig["Backend Config"]:::config
            DBConfig["Database Config"]:::config
            AppFactory["Application Factory"]:::config
        end
    end

    subgraph DB["Database Layer"]
        direction TB
        Users["Users"]:::db
        Pets["Pets"]:::db
        Locations["Locations"]:::db
        Notifications["Notifications"]:::db
        FCMTokens["FCM Tokens"]:::db
        Migrations["Database Migrations"]:::db
    end

    FCM["Firebase Cloud Messaging"]:::external

    %% Relationships
    MobileApp --> API
    WebApp --> API
    API --> DB
    NotifService --> FCM
    
    %% Click Events
    click Auth "https://github.com/fliotta/puppysignal/blob/master/backend/server/routes/auth.py"
    click PetMgmt "https://github.com/fliotta/puppysignal/blob/master/backend/server/routes/pet.py"
    click NotifService "https://github.com/fliotta/puppysignal/blob/master/backend/server/routes/notification.py"
    click ProfileMgmt "https://github.com/fliotta/puppysignal/blob/master/backend/server/routes/profile.py"
    click ScanService "https://github.com/fliotta/puppysignal/blob/master/backend/server/routes/scan.py"
    click DataService "https://github.com/fliotta/puppysignal/blob/master/backend/server/routes/data.py"
    
    click Users "https://github.com/fliotta/puppysignal/blob/master/backend/server/models/user.py"
    click Pets "https://github.com/fliotta/puppysignal/blob/master/backend/server/models/pet.py"
    click Locations "https://github.com/fliotta/puppysignal/blob/master/backend/server/models/location.py"
    click Notifications "https://github.com/fliotta/puppysignal/blob/master/backend/server/models/notification.py"
    click FCMTokens "https://github.com/fliotta/puppysignal/blob/master/backend/server/models/fcmtoken.py"
    
    click AuthView "https://github.com/fliotta/puppysignal/blob/master/mobile/views/Auth/index.tsx"
    click PetView "https://github.com/fliotta/puppysignal/blob/master/mobile/views/Pets/index.tsx"
    click ProfileView "https://github.com/fliotta/puppysignal/blob/master/mobile/views/Profile/index.tsx"
    click LocationView "https://github.com/fliotta/puppysignal/blob/master/mobile/views/PetLocations/index.tsx"
    click PetCreation "https://github.com/fliotta/puppysignal/blob/master/mobile/views/PetCreation/index.tsx"
    click MobileAPI "https://github.com/fliotta/puppysignal/tree/master/mobile/api/"
    
    click FoundPage "https://github.com/fliotta/puppysignal/blob/master/found-webapp/src/pages/Found/index.tsx"
    click PetServices "https://github.com/fliotta/puppysignal/blob/master/found-webapp/src/services/petservices.ts"
    
    click BackendConfig "https://github.com/fliotta/puppysignal/blob/master/backend/server/config.py"
    click DBConfig "https://github.com/fliotta/puppysignal/blob/master/backend/server/database.py"
    click AppFactory "https://github.com/fliotta/puppysignal/blob/master/backend/server/factory.py"
    
    click Migrations "https://github.com/fliotta/puppysignal/tree/master/backend/migrations/versions/"

    %% Styling
    classDef mobile fill:#3498db,stroke:#2980b9,color:#fff
    classDef web fill:#2ecc71,stroke:#27ae60,color:#fff
    classDef api fill:#e74c3c,stroke:#c0392b,color:#fff
    classDef db fill:#f1c40f,stroke:#f39c12,color:#fff
    classDef config fill:#9b59b6,stroke:#8e44ad,color:#fff
    classDef external fill:#95a5a6,stroke:#7f8c8d,color:#fff
```
