Victus is a personalized nutrition and healthy-lifestyle agent designed to turn scientific evidence, user context, and specialized tooling into practical recommendations.
The product is centered on the Victus Agent: the conversational system that coordinates user context, scientific retrieval, domain tools, safety controls, and persistent product state.
Scientific Processing, Retrieval, Fullstack, and Infrastructure exist to support that product goal.
Victus aims to help users make better nutrition and healthy-lifestyle decisions by combining:
The intended result is not a generic health chatbot or scientific search engine.
Victus is intended to provide grounded, personalized, actionable guidance while keeping scientific provenance and user context explicit.
Victus is designed to adapt recommendations to the user's profile, preferences, restrictions, goals, logged behavior, and relevant history.
This is the primary product capability toward which the other subsystems contribute.
Scientific papers are processed into structured evidence so the Agent can eventually retrieve evidence relevant to a user's request.
The scientific pipeline and retrieval system are separate:
Scientific Papers
↓
Scientific Processing
↓
Canonical Evidence
↓
Scientific Retrieval
↓
Victus Agent
Scientific Processing produces evidence.
Retrieval finds and ranks it.
The Agent interprets that evidence in the context of the user.
Victus uses controlled tools for actions that should not be handled through unrestricted model output.
Examples include:
The model can propose actions, but persistent changes should pass through explicit runtime boundaries.
The Agent is the main coordinator of the system.
A conversation may involve:
Not every interaction requires every subsystem.
At the highest level:
The exact degree of integration differs between subsystems and is documented in Current Status.
The conversational orchestration runtime.
It owns model coordination, safety flow, tool execution, clarification and confirmation, bounded conversational memory, and final response composition.
The current active public tool capability is focused on meal and beverage capture.
The scientific evidence pipeline.
It transforms research papers into structured scientific artifacts suitable for downstream retrieval.
Processing is one of the most mature technical subsystems in Victus.
The subsystem responsible for indexing, retrieving, ranking, and evaluating scientific evidence.
The current victus-rag implementation is primarily a CLI-first retrieval and evaluation laboratory. Product-serving integration is still under development.
The user-facing web product.
It currently includes a React frontend, Hono backend, PostgreSQL persistence, authentication, conversation history, meal logging, FoodB catalog access, profile views, biometrics views, and an HTTP gateway to Victus Agent.
The shared runtime platform for Victus.
It defines Docker Compose stacks, VPS deployment, networking, PostgreSQL, Redis, SeaweedFS, LiteLLM, Langfuse, observability foundations, secrets management, and Wiki.js hosting.
Victus uses a lightweight C4-inspired documentation structure.
Explains Victus as a complete system, its users, and its external boundaries.
Describes the major Victus subsystems and how they relate.
Explains how information moves between the major systems.
Each major subsystem has one focused conceptual page:
Implementation-specific details remain in the corresponding repositories.
Contracts belong in the central documentation only when they define a boundary between systems.
Examples include:
Fullstack ↔ Agent
Scientific Processing ↔ Retrieval
Agent ↔ Retrieval
Repository-internal schemas, CLI formats, migrations, Qdrant payloads, or implementation-specific structures should remain local to the repository that owns them.
Victus documentation distinguishes between:
Implemented
Partial
Experimental
Planned
The presence of code, schemas, UI, or scaffolding does not automatically mean that a capability is active in the product.
The implementation state of each major capability is maintained in Current Status.
Wiki.js is the central documentation source for:
Repository documentation should focus on:
This keeps one authoritative source for each architectural concept.
Victus documentation follows a small set of rules:
Victus already contains most of the major technical foundations required for its intended product.
The primary challenge is now integration.
The most important missing product path is:
User
↓
Fullstack
↓
Agent
↓
User Context + Scientific Retrieval + Nutrition Tools
↓
Grounded Personalized Recommendation
See Current Status for the current implementation state and near-term priorities.