Build a notes app with sign-in and a database #
On this page
Prompt:
Build a web app where people sign in and keep their own notes.
This example uses the complete notes-app source. The browser signs people in. The backend saves each note for its verified owner, lists that user's notes newest first, and lets that user delete them.
A shared database is one monthly item for the application; stored files are charged by size (Stay inside the Free Allowance).
For a conversation with an AI, use Build an app with sign-in and AI.
What your AI tool does #
Your AI tool starts from the example, creates the application, submits its manifest, and deploys it. It checks sign-in and the separation between users' notes, and reports which checks it completed.
What you need #
- A connected AI coding tool.
- Room under the account's limit of 10 applications. The creation call refuses an account at its limit.
- A sign-in method to try, such as an emailed code, Google, or GitHub.
Before your AI starts #
For the AI tool: Read the skill:deploy, skill:add-sign-in, and skill:add-service skills through read_context, and keep their approval and verification rules. With a shell, read the files the scaffold writes. Without one, read the complete notes-app example, following its continuation fields until every file is read.
For an app the person keeps, use the turnzero command from its first deploy where it works. Use the command also for binary files, a second deploy, scaffolding, or local runs. With a shell, try the npx form first; no global installation is needed. The command needs Node.js 24 or later and an authorized computer. If the command cannot run, use the file route within its limits; a first simple test app the person will discard may also use files when none of those command uses applies.
Before choosing the file route, tell the person that deploy_files alone provides no local tests or local run. If you have no shell, or your shell is elsewhere, this route writes no project files on the person's computer.
Steps #
1. Create the application #
Read read_plan_quotas for the sizes' limits. Use the size the person named, or ask them to choose. With nobody to ask, use Shared 0.5 GB with its default sleep setting. Report that choice and that it draws the account's Free Allowance. Call create_application with that size and keep its identifier. If the account is full, follow Create the application. A new application has production only.
2. Take the complete example #
On the command route, if the person will run the commands, give them the command checklist before their first command. Before scaffolding, authorize that computer.
Use an empty project folder on the person's computer. If your shell is elsewhere, the person runs the scaffold in that folder in their own terminal. Give them the exact line below with <application id> replaced by step 1's identifier. On Windows, use npx.cmd in place of npx; it works in any Windows shell.
npx --no-update-notifier -y turnzero@latest scaffold --template notes-app --application <application id>
The command writes the app in app/, takes the Database and Account packages, installs dependencies, and runs the tests. Keep the generated files together, including migrations/0001_notes.sql.
Without a shell, read every file on the notes-app source page. Use the application paths in its file table; the download URLs' .txt suffix is not part of those paths. Keep the server modules, client files, package files, and migration. Read the tests too, even where you cannot run them.
For this file route, call read_library with no entry to read the inventory. Put the current names and versions of account and database in the manifest's packages list. Keep the example's file:lib/… dependencies and its pg dependency. Leave the two library folders out of deploy_files; Cloud fills them from the submitted manifest. The manifest's package rows explains this route.
3. Follow a note from sign-in to the database #
| File | What happens |
|---|---|
client/app.js |
The page reads /__account/me and lists notes with GET /api/notes. Show the user and sign out lists the members that /__account/me returns. The page posts a new note as JSON with a body member to /api/notes. Confirming deletion sends DELETE /api/notes/<id>. The browser sends its session cookie. |
src/session.mjs |
The Account client verifies the session and returns the user's id, or no user. |
src/server.mjs |
The notes route refuses an unverified request with 401 sign_in_required. A verified request passes the user's id to the data layer. |
src/db.mjs |
The data layer saves that id as the note's owner. It lists that user's rows newest first and deletes only a row whose owner and id both match. |
migrations/0001_notes.sql |
The migration creates the notes table with a body, a created_at time, and an index on owner, time, and id. The startup code applies migrations before the server listens. |
The list shows each note’s first line and date. Select one to read its full text, or choose New note to write one. Save note or Ctrl/⌘ + Enter saves it; the reader’s trash control asks for confirmation before deleting it.
Keep ownership in the backend. Never use an owner supplied by the browser in place of the verified user's id. Add a database explains the connection pool and later schema changes.
4. Submit the manifest and deploy #
Call submit_manifest with the application's identifier and the complete manifest, naming no local_run. It declares the database and accounts services. On the file route, include step 2's current package rows.
For a local run, follow the scaffold's printed steps after this submission. Run its provision line from app/ with nothing piped. If it prints a submit_manifest call, make that call and run the line it returns as given from app/.
Provision writes the local run's settings into .env; it is not needed to deploy. Once the settings are written, follow the scaffold's steps for running and shaping the app locally before the deployment check below.
Call read_app_sign_in and keep the sign-in methods the person chose. Until configured, an end-user realm enables Google, GitHub, emailed codes, and passkeys with open sign-up. An invited audience makes sign-up invitation-only.
Call check_deploy. Resolve its refusals and repeat after fixing what it reports. With the command, run the returned command_npx from app/, or command_npx_windows on Windows. Once the check passes, call deploy_command with the application identifier alone and run its returned command from app/, using the npx form first.
If npx cannot run and turnzero --version works, use the returned installed form. If neither runs, use the file route within its limits.
Without a shell, use check_deploy's without_command call with check_only: true and the complete file list at application-relative paths. Leave out node_modules, credentials, and the two library folders Cloud fills. After files_checked, call deploy_files without check_only, listing every file by its returned path and sha256. Send a file's content again if missing names its hash.
Inline files are limited to 512 KiB each; a stored entry avoids that per-file cap. List at most 200 files. Listed and filled files together must fit within 4 MiB, and each JSON request has a 4 MiB limit. Beyond those limits, follow Ways to deploy.
Follow the returned read_status call with wait_seconds until deployment ends. Read status before retrying an uncertain outcome. On deployed, record the version and hostname. For a refusal, follow its detail and deployment refusals.
With a shell, run the app's tests again after changing code. Without one, report that local tests were not run. File checks and a successful health check do not prove sign-in or the separation between users' notes.
5. Verify sign-in and private notes #
Check the deployed home page and /health. An anonymous GET /api/notes must return 401 with sign_in_required.
Open the app's deployed address and complete sign-in. The page should show the signed-in user and the notes list or composer. For automated sign-in, follow Test sign-in with test end users, including its credential requirements.
For first-deploy verification, a temporary test end user's signed-in reads or AI chat need no further confirmation, including removal of data those checks wrote. On an app with real users, creating or deleting notes is outside that allowance and requires approval on production.
Test note creation and deletion on an already enabled development environment. On an app with no real users and only its live copy, test those writes there freely. Check the release defines that case.
On an app with real users, ask the person to approve the specific production writes. A request to build, deploy, or test alone does not approve production note creation or deletion. Without a suitable environment or that approval, report the deployed write and ownership checks as unrun.
Report the test rows you wrote so the person can remove them before launch. Email beyond the person's own test addresses and paid calls with stored keys still need their request for this run.
Where those writes are authorized, use two test users. Add a distinctive note as the first user and confirm it appears in that user's list after reloading. Keep its id from GET /api/notes. Sign in as the second user and confirm the first user's note is absent.
Using the second user's session, send DELETE /api/notes/<id> for that test note; expect 404 not_found. Confirm the first user can still read it. Then delete it as the first user; expect 204 and confirm it stays absent after reloading. Delete only the authorized test notes. Sign out and check that the notes controls disappear.
Follow the test-user guide's cleanup steps and report any test notes left in the database. A test user's expiry does not remove the application's saved notes.
Report this example as notes-app sign-in and database. Record the environment, local test results, whether browser sign-in completed, the anonymous refusal, and the outcome of the two-user check. State each untested part.
Expected result #
The deployed app lets each signed-in user add, read, and delete their own notes. Notes remain in PostgreSQL after a page reload, and another user's list does not include them. The source and tests stay in the project, with local test results distinguished from deployed checks.
Refusals #
The Account, Database, and platform refusal reference cover other failures.
| Code | Cause | Remedy |
|---|---|---|
sign_in_required |
No session was verified. | Sign in on the deployed hostname, or use the test-user guide for an automated request. This refusal is expected in the anonymous check. |
invalid_note |
The body is missing, is not a string, or has fewer than 1 or more than 20,000 characters after trimming. |
Send a body string within those bounds. |
invalid_json |
The note request's body is not valid JSON. | Send a JSON object with a body member. |
json_required |
The POST's content type is not JSON (415). | Send Content-Type: application/json. |
body_too_large |
The POST's body exceeds 100,000 bytes (413). | Send a smaller JSON body; the note's character limit also applies. |
origin_refused |
A write's Origin differs from https:// plus APP_PUBLIC_HOST, where both are present (403). |
Open the app at its deployed hostname and write from its own page. |
not_found |
The delete path is invalid, or the note is absent or belongs to another user (404). | Reload your own list and use an id from it. A 404 does not establish whether another user owns the note. |
library_entry_not_served |
Cloud cannot fill a declared library copy at its recorded version. | Send the project's own copy. If the entry is served and the person chooses that version, update its manifest row, submit the manifest, and retry with the root file: dependency kept and the copy omitted. |
Related #
- notes-app example holds the complete app and its tests.
- Add sign-in to your app explains session verification.
- Add a database explains migrations, local runs, and database operations.
- Build an app with sign-in and AI builds the conversation example.
- Test your application locally explains tests over the package doubles.