Victus Fullstack is the user-facing web product of Victus.
It provides the browser application, authenticated product backend, persistent product state, meal logging experience, user profile views, biometrics views, conversation history, and the HTTP gateway used to communicate with Victus Agent.
The Fullstack subsystem does not contain the Agent, Retrieval, Scientific Processing, Phoenix, or production infrastructure. It integrates with those systems through explicit boundaries.
Victus Fullstack is responsible for:
Victus Fullstack does not own:
The subsystem is composed of three primary runtime elements:
The backend also acts as the product gateway to Victus Agent.
The browser does not communicate directly with the Agent or database.
The backend owns authentication, product data access, conversation persistence, and integration with external Victus services.
The frontend provides the main Victus product experience.
Its current application areas include:
Some UI elements still represent demo or product-shell behavior and should not be interpreted as active backend capabilities.
In particular, static nutrition-focus content, evidence cards, landing-page nutrition values, and chat trace displays are not currently backed by real Retrieval or Agent evidence data.
The web application should remain focused on presentation and user interaction rather than owning business or integration logic.
The Hono backend is the application boundary between the browser, PostgreSQL, and external Victus services.
It is responsible for:
The backend should not reimplement Agent reasoning or scientific retrieval behavior.
External systems are accessed through explicit gateway boundaries.
Victus Fullstack is currently the source of truth for product users and sessions.
The product supports email and password authentication.
Passwords are stored using Argon2-derived hashes.
Authenticated sessions use browser cookies with short-lived access tokens and rotating refresh tokens. Revocable session state is persisted in PostgreSQL.
Unsafe browser requests are protected through CSRF controls.
Google authentication is partially integrated through Better Auth. UI and provider configuration exist, but the current migration/runtime path has not yet been fully validated.
After external provider authentication, Victus establishes its own product session rather than allowing the external identity provider to become the application session authority.
The Fullstack backend propagates the authenticated user identity to Victus Agent when making chat requests.
The model is never responsible for establishing user identity.
Victus Fullstack owns product-visible persistent state.
Conceptually:
Fullstack PostgreSQL
Users
Sessions
Profile
Biometrics
Preferences
Conversations
Messages
Meals
Food Catalog
Integration Outbox
This database is independent from Victus Agent persistence.
The Fullstack and Agent systems exchange logical identifiers and authenticated requests rather than sharing a database.
The backend stores and exposes user profile information, biometrics, and preferences.
The current product can read and display this information.
Backend write operations for biometrics and preferences exist, but the product UI does not yet provide complete onboarding and editing flows for all of them.
These values are product-owned state unless explicitly synchronized to another Victus subsystem through a defined contract.
The Fullstack database therefore remains authoritative for the product-facing representation currently implemented.
The product includes a FoodB-based food catalog.
Users can search the catalog, inspect foods, and record consumed meals.
The food catalog is stored in PostgreSQL after being materialized from the repository data source.
At present, this materialization is an explicit operational step rather than part of a fully automated environment bootstrap.
Meal records are persisted by Fullstack.
A meal write also creates an entry in a transactional outbox intended for delivery to Victus Agent.
The Publisher → Agent path is part of the intended architecture but is not currently implemented.
The outbox therefore represents a pending integration boundary rather than an active end-to-end workflow.
Meals remain safely persisted in Fullstack even when delivery to the Agent has not occurred.
Chat is the main active integration between Fullstack and Victus Agent.
The backend persists the user request before invoking the Agent.
This means conversation history remains product-owned even when the external Agent is temporarily unavailable.
The Fullstack stores conversations and messages for listing, recovery, and archival.
The Agent maintains its own orchestration state and conversation execution state independently.
The product and Agent therefore have related but different conversation responsibilities:
Fullstack
→ conversation history visible to the user
Agent
→ execution state required to continue reasoning
These two representations must be connected through stable logical conversation identifiers.
The current active Agent integration is an authenticated HTTP request from the Fullstack backend to the external Victus Agent.
Conceptually:
Fullstack Backend
↓
Authenticated Chat Contract
↓
Victus Agent
The backend forwards the authenticated user identity and propagates relevant tracing headers.
Victus Agent is not part of the Fullstack deployment and must be available independently.
If the Agent is unavailable or returns an error, the product surfaces that failure rather than generating a local fallback answer.
This preserves a clear boundary between product delivery and conversational reasoning.
Victus Fullstack does not communicate directly with Scientific Processing.
It also does not currently communicate directly with Victus Retrieval.
The intended product flow is:
User
↓
Fullstack
↓
Agent
↓
Retrieval
↓
Scientific Evidence
This keeps scientific retrieval and reasoning behind the Agent boundary rather than exposing them directly to the browser.
UI elements that visually represent evidence should only be treated as real evidence views once the Agent and Retrieval integrations provide the required data contract.
The current weekly plan experience is a view over logged meals.
It should not currently be described as a generated dietary plan or recommendation engine.
The product supports meal categories in its backend model, but current UI behavior does not yet expose the complete intended planning experience.
Future generated dietary planning should remain a separate product capability coordinated through Victus Agent rather than being inferred from the existing meal calendar.
PostgreSQL is the authoritative persistence layer for Fullstack-owned data.
It currently stores product identity, sessions, user-facing profile data, biometrics, preferences, conversations, messages, meals, food-catalog state, and integration outbox records.
Physical schema details belong to the repository implementation and database migration system.
The Wiki documents ownership and conceptual relationships rather than copying table definitions.
The current backend still performs schema initialization during application startup and contains transitional database behavior from the ongoing backend migration.
A production-ready version should use versioned migrations instead of runtime DDL as the long-term schema-management strategy.
The backend includes optional tracing instrumentation.
Trace context can be propagated to external systems such as Victus Agent.
The current local development environment does not include Phoenix as part of the Fullstack Compose stack.
Observability should therefore be treated as an integration capability rather than a locally guaranteed service dependency.
The Fullstack should expose enough telemetry to diagnose:
The current product runtime consists primarily of:
React Frontend
↓
Hono Backend
↓
PostgreSQL
Victus Agent remains an external dependency.
The local environment does not currently provide a fully reproducible integrated Victus runtime containing Fullstack, Agent, Phoenix, and all required data materialization steps.
FoodB catalog materialization is also currently an explicit setup step.
The repository's local runtime should eventually make the minimum product dependencies reproducible without requiring undocumented manual preparation.
Victus Agent
Provides conversational reasoning and controlled capability execution.
PostgreSQL
Stores Fullstack-owned product state.
FoodB Data
Provides the source catalog used for local food search and meal logging.
Google / Better Auth
Provides optional external authentication for Google login.
OpenTelemetry-compatible infrastructure
Receives optional application tracing when configured.
Victus Retrieval and Scientific Processing are not direct dependencies of Fullstack.
The current Fullstack already provides a substantial functional product foundation.
Implemented areas include:
Partially implemented areas include:
Not currently implemented include:
The product should therefore be considered a functional web application foundation with an active Agent chat boundary, but not yet a fully integrated Victus product environment.
User sessions, product-visible conversations, meal logs, and product-facing profile data remain responsibilities of Fullstack unless an explicit cross-system contract transfers or synchronizes them.
The backend forwards authenticated requests but does not reproduce Agent logic.
The frontend should not communicate directly with databases or internal Victus services.
External systems are accessed through stable gateways and contracts rather than shared persistence.
Important user actions should be durably recorded before depending on external services whenever the workflow allows it.
Fullstack and Agent may reference the same user or conversation, but each system owns different state and does not share its database.
Demo content, static evidence displays, and incomplete integrations must not be documented as active product capabilities.
The Wiki explains Fullstack ownership, architecture, and system boundaries.
The victus-fullstack repository defines exact routes, schemas, frontend behavior, database migrations, Docker setup, local operations, and implementation details.