System Architecture
A technical overview of Spiral’s hybrid on-chain and off-chain architecture.
Architectural Overview
Spiral is built on a hybrid architecture that deliberately separates source of truth, performance, and user experience.
The system combines:
- On-chain programs for identity, ownership, and integrity guarantees
- Off-chain infrastructure for performance, searchability, and UX
- Cryptographic bridges to keep both layers consistent
This approach avoids overloading the blockchain while preserving strong security guarantees.
Core Stack
Solana (Anchor)
Rust-based programs responsible for Organizations, Film registration (Token-2022 NFTs), and Preservation contracts.
Authentication & Identity
Hybrid authentication model combining wallet signatures (SIWS) and JWT-based sessions.
API Backend
Edge-first backend responsible for validation, indexing, authorization, and orchestration of on-chain actions.
PostgreSQL (Metadata Layer)
Read-optimized database used for metadata search, access control, and mirroring on-chain state.
The Hybrid Trust Model
Spiral follows a dual-layer trust model:
| Layer | Responsibility | Trust Level |
|---|---|---|
| Blockchain (Solana) | Identity, ownership, integrity, authorization | Source of truth |
| Backend + Database | Search, UX, permissions, caching | Derived / verifiable |
The backend never invents state.
All critical permissions are validated against on-chain PDAs.
Why Not Query the Blockchain on Every Request?
Querying the blockchain for every user interaction would:
- Increase latency
- Increase RPC costs
- Harm user experience
Instead, Spiral uses PostgreSQL as a projection layer:
- On-chain events are indexed
- PDAs are mirrored
- Queries become fast and expressive
On-chain data can always be re-verified cryptographically.
Deterministic Identity (PDAs)
All identities in Spiral are derived deterministically using Program Derived Addresses.
Example — Member PDA derivation:
This guarantees:
- No forged identities
- No duplicate members
- Deterministic verification without storage overhead
Technical Deep Dives
Continue reading to explore each subsystem in detail:
- Authentication & Identity → Wallet-based login, onboarding via invite, session model
- On-Chain Programs → Organization, Film, Preservation architecture
- Synchronization Layer → How blockchain events update the database
Monorepo Architecture
Spiral uses a monorepo structure. Backend and frontend are isolated but share types and schemas.