Fasq Architecture

Package Topology

Fasq is a package ecosystem with clear role boundaries:

• fasq core: query lifecycle, cache behavior, retries, invalidation, mutation orchestration, and diagnostics.
• fasq_hooks, fasq_bloc, fasq_riverpod: framework-specific adapter APIs that map core primitives into each state-management style.
• fasq_security: encryption and secure persistence helpers.
• fasq_serializer_generator: code generation support for typed query key serialization.

Request-to-UI Flow

1. UI adapter call (useQuery, QueryCubit, queryProvider, or core QueryBuilder) registers a query key + query function.
2. Core cache checks existing state and freshness window.
3. Query execution path runs async fetch, updates query state machine, and emits snapshots.
4. Adapter layer rehydrates UI with loading/data/error states.
5. Optional invalidation/refetch policies run based on mutation outcomes or manual client actions.

Mutation and Cache Coordination

• Mutations can apply optimistic updates before network completion.
• Success path can invalidate related query keys for consistency.
• Failure path can roll back optimistic state.
• Offline queue workflows defer network execution while preserving intended operation order where configured.

Security and Persistence Integration

When security features are enabled:

• Serialization occurs before encryption.
• Encrypted payloads are persisted through configured providers.
• Key material remains in platform-secure storage layers and is accessed through security plugin abstractions.

Security and persistence are opt-in integration layers on top of core query/mutation flows.

Diagnostics and Observability

Core diagnostics export:

• Cache hit/miss and usage visibility.
• Query performance timings and counts.
• Optional throughput windows for query activity tracking.

Adapter-specific docs include framework-first diagnostics usage, while core metrics remain the source of truth.

Design Constraints and Boundaries

• Fasq focuses on server-state orchestration; it is not a full domain-state framework replacement.
• Transport/auth concerns remain outside Fasq and should be handled by your API client stack.
• Performance outcomes depend on payload size, adapter usage style, and platform/device profile.

Related Docs

• Core Package Introduction
• Fasq Security Model
• Benchmarks and Limitations