Technical Architecture

Architecture Principles

Lifetopia is being developed as a connected product ecosystem rather than one large application. Each product has a focused responsibility while sharing identity, data contracts, design foundations, and public development evidence.

The architecture prioritizes incremental delivery. Existing products can remain independently accessible while deeper connections are introduced during Beta development.

• Separate applications with clearly defined product responsibilities.
• Shared authentication, profile, types, services, and document metadata.
• Public products remain usable during gradual integration.
• Blockchain functionality is introduced as an optional utility layer.

System Landscape

The current architecture consists of multiple public web applications, a playable game, shared workspace packages, Supabase services, and future Solana-connected systems.

Web Platform Monorepo

The public web platform uses Next.js App Router, TypeScript, Tailwind CSS, Turborepo, and pnpm workspaces. Applications are separated under the apps directory while reusable foundations are stored under packages.

• apps/website — the main project website and authentication entry point.
• apps/community — player community, profiles, posts, comments, likes, and bookmarks.
• apps/grants — funding review portal and delivery proposal.
• apps/docs — official public project documentation.
• packages/lib — shared Supabase and application utilities.
• packages/types — shared TypeScript contracts.
• packages/docs-data — shared bilingual documentation metadata and content.
• packages/devtools — internal project status and documentation tooling.

Playable Game Application

The playable game is treated as a separate product application because its runtime, asset pipeline, performance requirements, and release process differ from the Next.js web platform.

The publicly accessible build remains the previous Alpha version while the connected Beta foundation is being completed. Game integration should rely on defined identity and backend contracts rather than directly coupling the game to individual web application internals.

• Separate game runtime and asset delivery.
• Shared player identity through backend contracts.
• Progress, inventory, and economy data synchronized through approved services.
• Public Alpha and future Beta builds remain clearly identified.

Shared Authentication Flow

Lifetopia is designed around one account that can be used across its public products. Supabase Auth manages the underlying user identity, while the profiles table stores player-facing information.

When authentication begins from another Lifetopia application, the website receives a validated return destination. After successful sign-in, the user is returned to the originating product.

• Registration and password authentication are handled through Supabase Auth.
• profiles.id corresponds directly to the authenticated user ID.
• Cross-subdomain sessions use a shared cookie domain for lifetopiaworld.io.
• Protected pages verify authentication before returning private content.
• Return URLs must be validated to prevent unsafe external redirects.

Player Profile and Identity

The public player identity is stored separately from authentication credentials. This separation allows applications to display usernames, display names, avatars, countries, roles, and other approved profile information without exposing sensitive authentication data.

• Authentication credentials remain managed by Supabase Auth.
• Public profile fields are stored in the profiles table.
• Profile access is constrained through database policies.
• Game and marketplace systems should reference the same canonical player identity.

Database Foundation

Supabase PostgreSQL provides the current database foundation. Tables are organized around authenticated profiles, community interaction, public development evidence, and future connected product systems.

• profiles — canonical public player profile records.
• community_posts — community posts created by authenticated users.
• community_comments — comments connected to community posts.
• community_likes — per-user post reaction records.
• community_bookmarks — private saved-post relationships.
• development_logs — public repository and development activity records.

Database Security and RLS

Row Level Security is used to restrict direct database operations. Public content can be readable where appropriate, while user-owned records require authenticated ownership checks.

• Users can only modify profile and community records permitted by policy.
• Private relationships such as bookmarks remain scoped to their owner.
• Administrative operations should be performed through protected server environments.
• Service-role credentials must never be exposed to browser applications.

Deployment Architecture

Each public web application is deployed independently so it can have its own domain, environment variables, release lifecycle, and rollback path.

• lifetopiaworld.io — main website and authentication entry point.
• community.lifetopiaworld.io — community platform.
• grants.lifetopiaworld.io — funding review portal.
• docs.lifetopiaworld.io — public documentation portal.
• play.lifetopiaworld.io — public playable game build.
• Shared production configuration is coordinated through environment variables and documented domain rules.

Solana Integration Direction

Solana integration is planned as a gradual product layer. The system should first establish a normal Lifetopia account, then allow the player to connect a supported wallet when blockchain utility becomes relevant.

Blockchain state should not replace all application data. Game progression, social interaction, moderation, and other high-frequency product data can remain off-chain while selected ownership and transaction records use Solana.

• Phantom and Solflare are the planned wallet entry points.
• Wallet connection remains optional for normal non-blockchain access.
• Initial Beta verification uses Solana devnet interactions.
• Ownership and marketplace functions should use explicit server and transaction validation.

Public Security Boundaries

This documentation describes the product architecture at a level useful for reviewers and contributors without publishing secrets or operational details that could weaken system security.

• No private keys, service-role secrets, or privileged environment values are published.
• Detailed policy definitions may be summarized rather than copied in full.
• Internal administrative routes and security response procedures remain private.
• Public contract or mint addresses should only be published after their intended network and status are verified.

Architecture Next Steps

• Complete shared identity integration across public products.
• Formalize game-to-platform service contracts.
• Document database relationships and data ownership boundaries.
• Implement and test optional wallet connection flows.
• Add architecture verification records as Beta systems are delivered.