Plings Frontend Overview

<– copied from Plings-Docs/frontend/overview.md –>

Architecture Principles

Plings uses a GraphQL-first, API-driven architecture designed to support both web applications and native mobile apps (iOS/Android) with consistent real-time functionality and state management through a unified interface.

1. GraphQL-First Design

  • All functionality is exposed via a single, strongly-typed GraphQL endpoint.
  • The GraphQL schema serves as the contract between the frontend and backend, enabling type safety and discoverability.
  • Clients can request exactly the data they need, eliminating over-fetching and under-fetching.
  • The API’s structure naturally mirrors the underlying graph database (Neo4j).

2. Real-time Synchronization via Subscriptions

  • GraphQL Subscriptions provide real-time updates for all clients.
  • This unifies data fetching and real-time updates into a single paradigm, simplifying client-side logic.
  • A single source of truth is maintained in the backend databases.

3. Progressive Enhancement

  • Web app works as a PWA foundation.
  • Native apps extend with platform-specific features, but consume the same GraphQL API.
  • Shared state management patterns are used across platforms.

Rationale for GraphQL

The decision to migrate from a REST + WebSocket architecture to GraphQL is driven by several key advantages:

Key Advantages

  • Efficient Data Fetching: Clients query for the exact data they need, reducing payload size and the number of network requests.
  • Graph-Native Synergy: The query language is a natural fit for our Neo4j graph database, making client-side data traversal intuitive.
  • Unified Interface: Queries (read), Mutations (write), and Subscriptions (real-time) are handled through a single endpoint and protocol, simplifying the frontend architecture.
  • Strongly-Typed & Self-Documenting: The schema provides a reliable contract and enables powerful developer tools like GraphiQL.

Acknowledged Challenges

  • Backend Complexity: Requires implementing resolvers, the DataLoader pattern to prevent N+1 queries, and careful schema design.
  • File Uploads: Requires implementing a specific GraphQL multipart request specification.
  • Security & Caching: Requires more sophisticated strategies for query cost analysis, rate limiting, and caching compared to a standard REST API.