RE:ENTRY

Safe, evidence-grounded planning for a smarter return to everyday life after concussion.

Comment 5

Inspiration

Recovering from a concussion creates a practical problem that is easy to overlook: knowing what to do next.

A person may know their symptoms, but that does not necessarily answer whether they should spend two hours studying, return to work, exercise, or take another rest day. The decision depends on both the planned activity and how they have been doing recently.

Most of the recovery tools we looked at focused on symptom tracking. We wanted to explore the other side of the problem: using the information already collected to help someone think about a planned activity before they do it.

That is the idea behind RE:ENTRY.

What it does

RE:ENTRY combines daily check-ins, recovery profiling, activity simulation, safety checks, evidence retrieval, and explainable planning in one workflow.

Users first record daily information such as symptoms, sleep, screen time, study or work time, mood, and whether symptoms became worse after activity. RE:ENTRY uses this history to build a Recovery Profile. The profile describes recent trends, data sufficiency, uncertainty, and observable patterns rather than trying to assign a clinical recovery score.

Users can then submit a planned activity as a what-if scenario. For example, they can test a two-hour coding session before actually doing it.

The Recovery Engine models the submitted plan across four dimensions:

  • Cognitive demand
  • Physical demand
  • Screen exposure
  • Recovery opportunity

The result includes the modeled demand levels, the plan's alignment with the recent recovery pattern, whether the plan is classified as modeled overload, and the factors responsible for that result.

If the plan is considered overloaded by the engineering model, the Planner generates alternatives. Depending on the submitted activities, this can mean removing an activity, reducing its duration, or postponing it. Each alternative includes its rationale, trade-off, and modeled demand so the user can compare the options instead of receiving a single unexplained recommendation.

The recommendation layer can also retrieve supporting evidence from the guideline corpus. Evidence shown to the user includes the source, page, section, and canonical URL.

RE:ENTRY also has a Guideline Assistant for questions about concussion recovery. It uses the same retrieval system to find relevant passages from the guideline corpus. If the retrieval system cannot find sufficiently relevant evidence, the assistant is designed to return no evidence rather than fill the gap with an unsupported answer.

A separate deterministic Safety Gate runs before the planning and evidence pipeline. When a safety condition requires escalation, downstream recommendation, retrieval, and language generation are stopped.

How we built it

We intentionally separated the system into several components instead of putting the entire workflow behind an LLM.

Recovery Engine

The Recovery Engine is implemented in Python and is deterministic.

It processes recent check-in data and produces a Recovery Profile containing the recent symptom trend, data sufficiency, uncertainty, and observed patterns. The same engine models planned activities across cognitive, physical, screen, and recovery dimensions.

The workload model is an engineering heuristic. It is not presented as a clinical exertion score or medical risk prediction. Keeping this distinction explicit was important because the same numerical output can otherwise be interpreted as something more clinically precise than it actually is.

Safety

Safety is implemented as an independent execution boundary.

The Safety module evaluates the submitted safety information before the Planner, RAG service, or LLM Composer can run. A blocked or review-required result prevents downstream processing.

This is enforced by the orchestration code itself. Safety is therefore not dependent on an LLM following instructions correctly.

Planner

The Planner is also deterministic.

It receives the scenario result and submitted activities and generates rule-based alternatives. The current strategies are removing an activity, reducing its duration, and postponing an activity.

The Planner does not decide whether a user is medically safe. It compares the submitted plan with alternative versions using the same engineering workload model.

RAG Evidence Service

The evidence layer is deployed as a separate FastAPI service.

The ingestion pipeline extracts and chunks the guideline PDFs, generates embeddings using sentence-transformers/all-MiniLM-L6-v2, and stores them in ChromaDB. Retrieval is then followed by reranking with cross-encoder/ms-marco-MiniLM-L-6-v2.

The current corpus contains three guideline sources:

  • Amsterdam 2022 Consensus Statement
  • Living Concussion Guidelines (Adults)
  • PedsConcussion

Audience filtering is part of retrieval. This matters because evidence for pediatric concussion should not be treated as interchangeable with evidence intended for adults.

The retrieval API returns the passage together with its source metadata and citation information. The backend validates this metadata before evidence can be shown as a recommendation citation.

We also added relevance handling for cases where the retrieval result is technically related to the query but not actually useful evidence. For the assistant, a weak retrieval result is treated as insufficient evidence instead of being presented as a confident answer.

LLM Composer

The LLM is deliberately kept at the final language layer.

The Planner has already selected the alternatives, and the RAG service has already retrieved the supporting evidence before the Composer receives them. The Composer's job is to turn those existing results into readable explanations.

It is not responsible for choosing the recommendation, generating clinical evidence, inventing citations, or making a diagnosis.

Claude is optional. When an API key is not configured, RE:ENTRY uses a deterministic template instead. The rest of the system therefore remains functional without an LLM.

Frontend

The frontend uses React, TypeScript, and Vite.

The main user flow covers check-ins, the Recovery Profile, activity simulation, explanation of the modeled result, comparison of alternatives, and supporting evidence. A floating Guideline Assistant provides a separate way to search the evidence corpus.

The frontend also keeps API contracts separate from presentation models through adapter functions. This prevents backend response structures from becoming tightly coupled to individual UI components.

Deployment

The application is structured for deployment as separate services.

The Render Blueprint provisions the backend, RAG service, frontend, and managed PostgreSQL database. Service configuration is passed through environment variables rather than relying on local development paths.

The backend uses DATABASE_URL in deployed environments while retaining SQLite as a local development fallback.

The RAG service builds its vector index during the Docker image build. This is important for the target deployment environment because the service should not depend on persistent local disk state being available after deployment.

Challenges we ran into

One of the biggest challenges was deciding what the LLM should actually be allowed to do.

An early version could have been much simpler: send the user's symptoms and planned activity to a model and ask it what the user should do. We decided against that architecture because it would make the most important decision in the system difficult to test and reproduce.

Instead, we made the Planner deterministic and limited the LLM to language composition. This created more implementation work because the planner, evidence retrieval, validation, and wording layers all had to communicate through explicit contracts. In return, each part can be tested independently.

Retrieval was another problem.

During early testing, the RAG system could return a real passage that looked relevant but did not actually support the question. The problem was particularly important for the Guideline Assistant because showing a real citation can make an answer appear trustworthy even when the retrieved passage is a poor match.

We therefore added relevance filtering and an explicit no-evidence behavior. A retrieval failure is treated as a retrieval failure; it is not passed to the language model as an invitation to guess.

We also had to resolve a number of deployment-specific issues. The backend originally relied on a local SQLite path, while the deployed architecture required PostgreSQL through an environment-provided database URL. The RAG service had a similar problem because its vector database could not rely on persistent local storage in the target environment. Building the retrieval index into the Docker image gave us a predictable starting state for each deployment.

Accomplishments we're proud of

The strongest part of RE:ENTRY is the separation between decision-making, evidence, and language generation.

The system can run without Claude. The Recovery Engine and Planner remain deterministic, Safety remains an independent gate, and the RAG service can operate independently of the language model.

We also made citation completeness part of the backend contract. A retrieved passage needs a source ID, title, canonical URL, page, section, and citation before it can be treated as recommendation evidence.

Another important decision was to distinguish three different types of information throughout the system:

Observed information comes from the user's check-ins.

Engineering inference comes from the workload and planning models.

Clinical evidence comes from the retrieved guideline corpus.

Keeping these categories separate prevents a modeled workload level from being presented as if it were a clinical measurement.

The current implementation has 112 backend tests and 10 RAG tests covering the main recovery, safety, planning, and retrieval behavior.

What we learned

The main lesson from building RE:ENTRY was that using an LLM responsibly required us to reduce its responsibilities rather than increase them.

Once the LLM was moved to the wording layer, several other design decisions became clearer. The Planner had to expose explicit alternatives. The retrieval service had to return structured citations. Safety had to exist outside the recommendation logic. The frontend needed to distinguish modeled results from clinical evidence.

This also made failures easier to reason about. If an answer is wrong, we can investigate whether the issue came from the safety rules, recovery model, planner, retrieval system, or language layer instead of treating the entire system as one opaque prediction.

For a health-related application, that separation is more useful to us than simply getting a more convincing answer from a larger model.

What's next

Expanding the retrieval evaluation

The current retrieval benchmark is based on a small curated set. We want to expand it with adversarial queries, multilingual questions, explicit no-evidence cases, and more difficult audience-filtering cases.

Building a Clinical Evidence Matrix

We plan to maintain a structured mapping between claims the system can present and their supporting evidence. Each entry would include the source, population, page or section, evidence type, and clinical-review status.

This would make it easier to audit the evidence layer as the number of supported scenarios grows.

Improving longitudinal modeling

The current Recovery Profile works from a limited history of self-reported check-ins. A future version should make better use of longer-term patterns while keeping the same distinction between observed user data, engineering inference, and clinical evidence.

The goal is not to turn more data into a medical diagnosis. The goal is to make the planning context more useful while keeping the system's limitations explicit.

Built With

+ 18 more
Share this project:

Updates

posted an update —

RE:ENTRY is ready for judging. We built it to help people make sense of their recovery and plan everyday activities after a concussion. The final version brings together check-ins, safety screening, activity simulation, recovery planning, evidence-based recommendations, and our AI Guideline Assistant. We also spent the final stage testing the full workflow, fixing issues, and polishing the experience for the demo.

Thanks for following our journey with RE:ENTRY.

Log in or sign up for Devpost to join the conversation.

Submission history