Nextube

Nextube is a protocol-first multimedia platform foundation for cloud-native cards, streams, live rooms, and future interface layers.

Backbone

The protocol layer lives in src/protocol and defines:

• a fixed protocol identity and version
• a closed set of content kinds for cards and streams, including native game cards
• immutable envelope shapes for cards, collections, and streams
• room for metadata, relations, and future delivery layers without breaking the core

The storage backbone lives in src/store and uses a local, service-free layout:

• append-only segment records for protocol envelopes and metadata
• content-addressed blob shards for large media payloads
• lightweight reference files for fast lookup without an external database
• one workspace-wide disk root so all data stays native and unified

Native runtime infrastructure

The store module includes a native runtime infrastructure layer in src/store/runtime-infrastructure.ts with local in-process execution:

• native mode (default): in-process cache, message bus, and queue

Runtime selection:

• no external service configuration is required

Native cache and queue tuning (optional):

• NEXTUBE_NATIVE_CACHE_MAX_ENTRIES (default 50000)
• NEXTUBE_NATIVE_CACHE_DEFAULT_TTL_SECONDS (default 15)
• NEXTUBE_NATIVE_CACHE_JANITOR_MS (default 5000)
• NEXTUBE_NATIVE_QUEUE_MAX_SIZE (default 20000)

Fallback behavior:

• native runtime starts with no network dependency and serves traffic locally

Hot-path upgrades currently wired:

• envelope/list APIs use short-lived cache entries for repeated reads
• engagement reads/writes use cache-backed fast path
• cache uses bounded LRU + TTL expiration + periodic janitor cleanup
• concurrent cache misses collapse into a single compute path (getOrCompute) to reduce thundering-herd overhead
• like/comment updates are now serialized per-card with in-process locking to reduce lost updates under concurrent writes
• store mutations publish events onto the runtime bus and enqueue records onto store-events
• auth token/user lookups and user list reads use short-lived cache acceleration
• currency overview and snapshot reads use short-lived cache acceleration

Current scope note:

• this is still a local-first single-node architecture
• native runtime improves cache and async coordination behavior but does not convert the system into a distributed transactional database with consensus semantics

Current status

The single Node.js application in src contains both:

• an admin-focused operations experience for inventory, envelopes, blobs, and references
• a client-style feed experience for scrolling, likes, and comments

The internal protocol and store modules remain the durable backbone that these interfaces build on top of.

Auth and role management

The local store now includes first-class user and role records under .nextube-data/data/auth:

• user registration with username + password and either email or phone
• login with email, phone, or username
• profile update support for display name, avatar URL, bio, username, email, and phone
• password change flow with current password verification
• role management with system roles (role-admin, role-moderator, role-user)
• admin user management for role assignment and account status (active / disabled)

API routes in src/app/api:

• POST /api/auth/register
• POST /api/auth/login
• POST /api/auth/logout
• GET /api/auth/profile
• PUT /api/auth/profile
• POST /api/auth/password
• GET /api/admin/users
• PATCH /api/admin/users
• GET /api/admin/roles
• POST /api/admin/roles

Auth token usage:

• send Authorization: Bearer <token> or x-nextube-token: <token>
• token is returned by register/login and stored server-side as a hashed session token

V1 launch baseline

Application scripts:

• npm run dev to start the application in development mode
• npm run build and npm run start to build and serve the production application
• npm run typecheck to validate TypeScript
• npm run engine to run the currency engine, with -- --once for one cycle
• npm run seed to rebuild sample data, with optional -- --profile=extreme or -- --users=<count> arguments
• npm run benchmark -- ... to benchmark local-store throughput

Feed profile metrics:

• profile balance label uses the configured system currency identity (symbol/name) from store identity state
• Drop % is computed server-side from global activity:
  • per-user score: content * (1 + 0.01 * (likes + comments))
  • drop share: (userScore / sumOfAllUserScores) * 100
  • response precision is fixed to two decimal places for UI consistency

Maintenance guidance:

• keep API-derived profile metrics in API routes instead of recomputing from partial client lists
• prefer typed shared response payloads when the same route is consumed in multiple client flows
• keep protocol envelope fields backward-compatible and additive for v1 stability

Operational guidance:

• use the native runtime queue and bus hooks for asynchronous background workflows
• keep local store data (.nextube-data) on fast SSD/NVMe
• monitor queue lag and cache hit ratio before increasing worker complexity