SS
AppTeam eStore Platform Documentazione pubblica
Landing Indice documenti
Architettura

Architettura Sistema

La panoramica completa della struttura della piattaforma: madre, client master, release, installazioni e ruoli dei diversi componenti.

Torna all'indice Vai alla landing

1. Scopo del prodotto

AppTeam eStore e' un ecosistema composto da una piattaforma madre e da un prodotto client vendibile. La documentazione pubblica e marketing vivono sulla madre, mentre il codice operativo del prodotto finale vive nel client master.

Nel perimetro del prodotto client troviamo:

  • backend Laravel
  • app mobile Flutter
  • integrazione Shopify
  • push notifications OneSignal
  • pannello admin server-rendered

L'obiettivo non e' costruire un semplice frontend mobile collegato direttamente a Shopify, ma un prodotto rivendibile in cui Laravel diventa il centro operativo della piattaforma.

2. Principio architetturale principale

La fonte primaria dei dati commerciali resta Shopify, mentre Laravel governa:

  • installazione
  • configurazione
  • branding
  • contenuti editoriali
  • visibilita' delle categorie
  • slide promozionali
  • accessi admin
  • sessioni cliente mobile
  • registro dispositivi push
  • invio notifiche
  • audit webhook

In sintesi:

  • Shopify e' il motore commerce
  • Laravel e' l'hub applicativo
  • Flutter e' il client mobile finale

3. Vista ad alto livello

flowchart LR
    A[Admin Web Laravel] --> B[Core Laravel]
    C[Flutter App] --> B
    D[Install Wizard] --> B
    B --> E[(Database Locale)]
    B --> F[Shopify Admin API]
    B --> G[Shopify Storefront API]
    B --> H[OneSignal]
    F --> I[Catalogo e Webhook]
    G --> J[Checkout e Account Cliente]
    H --> K[Push Promozionali e Ordine]

4. Domini applicativi

4.1 Installation Domain

Gestisce il bootstrap dell'istanza:

  • verifiche ambiente
  • configurazione database
  • creazione primo admin
  • attivazione licenza locale
  • connessione Shopify
  • import iniziale
  • registrazione webhook
  • branding iniziale
  • completamento installazione

4.2 Admin Domain

Gestisce il pannello web autenticato:

  • dashboard
  • profilo admin
  • gestione altri admin
  • impostazioni app
  • catalogo visibile in app
  • slide home
  • notifiche push
  • strumenti Shopify

4.3 Catalog Domain

Gestisce il catalogo locale necessario alla mobile app:

  • prodotti
  • varianti
  • collezioni
  • mapping collezione-prodotto
  • immagini personalizzate categorie
  • criteri di visibilita'

4.4 Commerce Domain

Gestisce il checkout reale:

  • validazione linee carrello
  • verifica varianti locali
  • creazione cart Shopify via Storefront API
  • associazione buyer identity se il cliente e' loggato

4.5 Customer Account Domain

Gestisce l'identita' cliente lato app:

  • login cliente Shopify
  • registrazione
  • recupero password
  • sessione locale sicura
  • recupero profilo
  • lista ordini reale

4.6 Push Domain

Gestisce l'intero layer notifiche:

  • registrazione dispositivi
  • allineamento email dispositivo
  • notifiche manuali dal backoffice
  • notifiche automatiche sugli ordini
  • deep linking verso prodotto

4.7 Webhook and Sync Domain

Gestisce la consistenza del catalogo locale:

  • ricezione webhook firmati Shopify
  • audit eventi
  • sync delta catalogo
  • riallineamento mapping collection-product

5. Topologia reale della soluzione

La topologia attuale segue questo modello logico:

estore.appteam.it/                # madre: control center, docs, landing, licensing, release
|- backend/
|- public_html/
|- doc/

estoreclient.appteam.it/          # client master: prodotto ecommerce reale
|- backend/
|- public_html/                   # nome locale di questa istanza; nel bundle ufficiale diventa web_root/
|- mobile_app/

La cartella mobile_app/ appartiene quindi al client master. La madre conserva la documentazione tecnica e commerciale dell'app mobile, ma non ne deve mantenere la sorgente operativa.

6. Modello di deploy

Il deploy e' stato impostato per separare:

  • backend/ come core Laravel non esposto pubblicamente
  • una web root pubblica esposta dal dominio

Nella madre attuale la cartella pubblica e' public_html/. Nel bundle ufficiale del client master, invece, la web root viene normalizzata in web_root/ per adattarsi a server con nomi diversi della document root.

7. Modello dati essenziale

Entita' principali:

  • shops
  • shopify_connections
  • app_settings
  • products
  • product_variants
  • collections
  • collection_product
  • home_slides
  • push_devices
  • push_notifications
  • customer_sessions
  • shopify_webhooks
  • webhook_events
  • users

8. Relazioni principali

erDiagram
    shops ||--o{ app_settings : has
    shops ||--o{ products : has
    shops ||--o{ collections : has
    shops ||--o{ home_slides : has
    shops ||--o{ push_devices : has
    shops ||--o{ push_notifications : has
    shops ||--o{ customer_sessions : has
    shops ||--|| shopify_connections : has
    products ||--o{ product_variants : has
    products }o--o{ collections : belongs_to
    users {
        bigint id
        string name
        string email
        string password
    }

9. Ruolo del database locale

Il database locale non duplica Shopify per sostituirlo, ma per:

  • alimentare rapidamente la mobile app
  • disaccoppiare la UX dal runtime Shopify
  • supportare contenuti editoriali locali
  • applicare regole di visibilita'
  • memorizzare sessioni cliente e dispositivi push
  • avere audit trail su eventi e operazioni

10. Integrazioni esterne reali

10.1 Shopify Admin API

Usata per:

  • import iniziale
  • refresh catalogo
  • gestione webhook
  • lettura store e scope

10.2 Shopify Storefront API

Usata per:

  • checkout reale
  • account cliente
  • lista ordini
  • recupero password cliente

10.3 OneSignal

Usata per:

  • registrazione dispositivi
  • invio push manuali
  • push automatiche ordini
  • deep link prodotto

11. Pattern architetturali usati

11.1 Backend

Pattern principali:

  • controller sottili
  • service layer applicativo
  • Eloquent models per persistenza
  • middleware per gate di accesso
  • Blade per backoffice

11.2 Mobile

Pattern principali:

  • feature folders
  • repository HTTP
  • ChangeNotifier per stato locale
  • persistenza tramite SharedPreferences
  • navigazione manuale con Navigator

12. Decisioni architetturali gia' consolidate

  • il sistema e' pensato come single-shop
  • il catalogo mobile viene letto dal backend Laravel e non direttamente da Shopify
  • l'app supporta login cliente reale, non solo checkout guest
  • le push ordini si basano sull'email associata al device
  • il payload push replica i metadati prodotto in data e custom_data
  • il backoffice e' server-rendered e non SPA
  • il deploy separa core Laravel e document root pubblica

13. Vincoli tecnici importanti

  • per account cliente servono gli scope Shopify corretti
  • per il checkout reale i prodotti devono essere disponibili sul canale Storefront/Headless
  • per le push OneSignal vanno configurati app_id e chiavi corrette
  • la sessione cliente mobile e' locale al backend, non e' il token Shopify puro

14. Rischi architetturali principali

  • disallineamento tra catalogo Shopify e cache locale
  • webhook non ricevuti o HMAC non valido
  • token Shopify scaduti o scope insufficienti
  • device push registrati ma non correttamente associati a email cliente
  • installazioni self-hosted con permessi filesystem errati

15. Direzione evolutiva consigliata

I prossimi avanzamenti piu' naturali sono:

  • ruoli e permessi admin piu' granulari
  • audit log per azioni critiche backoffice
  • gestione ordine/admin piu' estesa
  • callback post-checkout e riconciliazione carrello
  • policy di sync piu' sofisticate
  • documentazione release e upgrade versionato