One working session · Git, Flutter, Python 3, a local database

Set up a local NRTR environment

Follow this once, in order. At the end, the phone or desktop client opens, talks to a service on your machine, and shows one health or training record that you seeded. It does not call a hosted backend for that check.

If a flag in the README disagrees with a command here, use the README. The order stays the same: database, then service, then client. Starting the client first opens a screen that cannot load data. That case is in When the local environment fails.

What “done” looks like

A local database accepts connections and contains one seeded record you can name.
The Python service answers a health check at the address in your environment file.
The Flutter client is pointed at that same address.
The client shows the seeded record.

If any of those four is missing, the setup is not finished. A clean flutter doctor is not a substitute for step 4.

The four parts you are starting

NRTR on a developer machine is four processes, not one application.

Part	What it owns	What it must not do
Database	The person’s observations, plans, and history.	Call a model or a vendor.
Python service	Validation, reads and writes, and calls that are allowed to leave the machine.	Store the only copy of a record in memory.
Flutter client	What the person sees and the actions they take.	Invent a result when the service is down.
Model process	A suggestion, when a task needs one.	Write the health record. Skip this process if your task does not need a suggestion.

You can leave the model process off for a user-interface task. Say so in the environment file. Do not point the client at a hosted model “so something comes back.”

Before you install

Check the tools. Do not install the repository until each check prints a version or a clear pass.

Check	Command	Pass	Fail
Git	`git --version`	A version line.	Install Git, then open a new terminal.
Python 3	`python --version`	Python 3.x. On some machines the command is `python3`.	If this prints Python 2, do not continue with that binary.
Flutter	`flutter doctor`	No errors for the device you will actually run: Android, iOS, desktop, or web.	A green web check does not mean a phone emulator is ready. Fix the device you will use.
Database	The client your team uses, pointed at localhost.	The server accepts a connection.	Start the database service before you clone. A missing database is slower to diagnose after the app is open.

Get the code

git clone https://github.com/xandernano/nrtr-health.git
cd nrtr-health
git status

git status should report a clean work tree on the default branch, unless someone told you to check out another branch. If it reports files you did not create, stop and ask. Do not commit them, and do not delete them.

Look at the top-level folders before you install packages. You should be able to point to the Flutter client, the Python service, and the place migrations live. If you cannot, read How the NRTR platform is divided and then come back. Installing every package in the tree hides which part failed.

Create the environment file

Secrets stay on your machine. They are not committed. Copy the sample file the repository ships, if it ships one, and fill only the values for the slice you are running.

Set the database address to the local server you already connected to in the prerequisite check.
Set the service port to a port that is free. Write that same port down. The client will need it.
Leave vendor keys empty unless the task you were given names a vendor.
Set the model flag off if you are not running the model process.

Do not paste a teammate’s file from chat

That file often points at their database, their port, or a hosted project. You will get a client that runs and a record you cannot see, because you are reading someone else’s machine.

Confirm the environment file is ignored by Git:

git status

The environment file must not appear as an untracked file you are about to add. If it does, fix the ignore rule before you continue. Do not “add it just this once.”

Install and start the Python service

python -m venv .venv

On Windows:

.venv\Scripts\activate

On macOS or Linux:

source .venv/bin/activate

Your prompt should show the virtual environment name. If it does not, the next install will land in the wrong Python.

python -m pip install -r requirements.txt

If the repository splits requirements by service, install the file for the service you are starting, not every file you can find. Then start the service with the command in the README, using the port from your environment file.

Check it from a second terminal, not from the client:

curl -sS http://127.0.0.1:PORT/health

Replace PORT with your port. You want a success body. Connection refused means the process is not listening. Read the service log before you change the client.

Create the local record store

NRTR used to keep these records in hosted collections. A documented move covered more than 100 stores and about 30 workflows. Your machine does not repeat that history. It applies the migrations on the branch you checked out, then loads the smallest seed that proves a read.

Apply migrations with the project command. If it prompts for the database address, it must match the environment file.
Load the seed for one known record. Write down its identifier.
Read that identifier through the service, with the service’s read route, not only with a SQL prompt.

A row that exists in SQL and does not come back from the service means the service is attached to a different database. Stop. Do not seed a second time until both tools print the same address.

Install and start the client

flutter pub get
flutter analyze

flutter analyze must finish without errors in the generated client code. Warnings that already exist on the branch are not your job to clear during setup. Errors that name a missing generated file mean the generator has not been run on this machine. Run the generator the README names. Do not hand-write the missing classes, and do not commit the generated output unless you were asked to.

Point the client at http://127.0.0.1:PORT, the same port the health check used. Start the client on the device flutter doctor cleared.

Confirm the four conditions

The health check still succeeds. Starting the client must not have killed the service.
The client shows your seeded record, with the identifier you wrote down.
Turn the network off, or stop only the service, and reload. The client must fail visibly. A quiet empty screen is a bug in the setup or in the error path, not a success.
Start the service again. The same record returns. You did not need to reinstall the client.

Step 3 matters. A setup that only works while everything is already running will waste the next person a day.

Leave the machine in a state someone else can use

The environment file is untracked.
You can say which port the service uses.
You can say the identifier of the seeded record.
You did not commit generated files or a database file.

If a later task fails, start from the symptom in the recovery procedures. Do not repeat this tutorial from the clone.

Where to go next

Record a health observation if your task writes data.
How the platform is divided if you are about to change a boundary.
Project records for coding tools if you will use a coding assistant on this repository.