Keystone documentation

The user manual, a day-in-the-life walkthrough, the technical architecture and the API. The demo's synthetic customer is Sthira Facility Services, Hyderabad, which runs four properties: Kaveri Heights (96 flats, Gachibowli), Orbit Tech Park Block B (20 office suites over 10 floors, HITEC City), Sai Plaza (shops and offices, Kondapur) and Shamshabad Logistics Park (10 warehouse bays).

1. Demo access

  1. Open keystone.ajaykongala.online/app. The demo signs you in as a temporary guest (guest-YYMMDD-xxxx) with no PIN or sign-up. Guests get the manager role so every screen is visible.
  2. The demo's data is synthetic and rebuilt from the seed whenever the server restarts, so change anything you like.

Resident pages (/r/… request form, /t/… tracking page) are public by design: residents never need an account. The on-site lane shows its seeded demo logins on the sign-in page; the hosted twin hides them.

2. Accounts and roles

RoleCan do
ManagerEverything: properties, occupants, work orders, assignment, assets, services, readings, gate, and user management.
HelpdeskLog and assign work orders, move occupants in and out, run the gate register, enter readings.
TechnicianStart, pause and resolve work assigned to them; record services; enter readings. Read-only elsewhere.

Sign-up is by invitation: a manager opens Users, creates an invite link for a role and sends it. The first account on an empty installation becomes a manager. Sessions are signed cookies valid for seven days.

3. Properties and units

Properties lists every property as a card: occupancy (occupied units over all units), open work, work past its SLA and overdue service. Open a property for the floor-by-floor unit grid (occupied, vacant, lease ends within 60 days), its open work, its systems with next service dates, 12-week meter charts and its resident request link.

Units. Click a unit to see its occupant, lease, monthly charge, history and work. Record move-in on a vacant unit or Record move-out on an occupied one; that is the only way a unit's status changes. A second move-in on an occupied unit is refused.

Occupants searches by name, phone, unit or email, and filters leases ending within 30, 60 or 90 days. Add property generates units from floors × units per floor, numbered 101, 102 … and exports go to CSV from each list.

4. Work orders and SLA

Log work from Work orders → Log work order, from a unit or asset page, or let the assistant fill the form from a pasted message. Numbers run WO-2026-0001 upward.

PrioritySLA windowTypical
Critical4 hoursperson stuck in a lift, smoke, gas smell, sparking
High1 dayno water, no power, lift down, AC off in an office
Medium3 daysleaks, seepage, corridor lights
Low7 daysrequests, loose hinges, fogging

Lifecycle. Open → assigned (needs a technician) → in progress ⇄ on hold (needs a reason; the SLA clock pauses) → resolved (needs a note of what was done, optional cost) → closed. Resolved work can be reopened; open or assigned work can be cancelled. Illegal steps such as closing open work are refused.

SLA state is computed each time a page is read: working time from logging to resolution (or now), minus time on hold, against the priority's window. Work resolved late stays "missed". The Board shows each technician's open queue oldest first; late work has a red edge.

5. Assets and service

Assets → Service schedule sorts every asset into overdue, due in the next 7 days, and later. Next due = last service date + interval (lifts and DG sets monthly, pumps every 60 days, fire systems quarterly, transformers half-yearly in the demo).

On an asset page, Record a service (date, type, who, checks, cost) writes the service log and moves the next due date. Future dates are refused. The AMC tile turns red 30 days before the annual maintenance contract ends. Report breakdown takes the asset out of service and raises a linked work order (critical for lifts and fire systems, high otherwise); when that work is resolved the page offers to return the asset to service.

6. Residents and the gate

Each property has a resident request link. QR poster on the property page prints it for the lift lobby. A resident types the problem in their own words, adds a flat number, name and phone, and is taken to a tracking page with the work order number and its progress. The tracking link is signed: changing it shows nothing, and it never shows staff names, notes or costs.

Gate is the digital visitor register: sign a visitor in (property, name, phone, unit visited, purpose, vehicle), mark them out, and see who is on premises now. Anyone in for more than 8 hours is flagged as an overstay.

7. Utilities

Each property has three meters: grid power (kWh), DG diesel (litres) and water (kL). Enter readings as the register shows them. Weekly use is the difference between successive readings; a value lower than the previous reading, or higher than a later one, is refused. The page shows 12 weekly bars per kind, a four-week comparison per property, and energy intensity in kWh per 1,000 sq ft. A week of diesel more than 1.5× the usual raises a "diesel spike" flag, which usually means a grid outage the DG covered.

8. Assistant

Open it from the top bar on any page. The badge says Using AI when a Claude or OpenRouter key is configured and Works without AI otherwise; every feature works in both modes.

  • Log a complaint: paste a message (English or Hinglish). You get category, priority, flat number and a title, plus the words that decided it. Use this on the form fills the work-order form. A model's answer is checked against the allowed categories and priorities and can never lower a critical safety call.
  • What needs me today: a ranked list across all properties (breached SLAs first, then unowned urgent work, assets down, overdue service, AMC renewals, diesel spikes, lease renewals, overstays), each with its reason. Ranking uses fixed rules so it is repeatable.
  • Brief on this property (on a property page): occupancy, open work, breaches, overdue service, energy intensity and the top recommendation, in plain sentences.

9. A day at the desk

08:45 Lakshmi, the facility manager, opens Today. Four jobs are past SLA; the top one is sparking at a distribution board in Shamshabad, 30 hours over. She reassigns it to Ramesh and calls the site supervisor.

09:10 The Sai Plaza Lift 2 breakdown from last night is still open. Imran is on it; Metro Lifts is due at 11.

10:30 A resident at Kaveri Heights scans the lobby poster: "Flat 905 mein subah se paani nahi aa raha". It lands as high-priority plumbing for flat 905. Farah at the helpdesk assigns Suresh; the resident's page now says Assigned.

12:00 Ramesh records the DG set 1 monthly load test at Orbit Tech Park from his phone; it drops off the overdue list.

15:00 The diesel spike flag at Orbit Tech Park lines up with Tuesday's grid outage. Lakshmi notes it for the owners' report.

18:30 The gate shows a painting crew signed in ten hours ago and not out: the overstay flag prompts a call to security.

10. Architecture and rules

One FastAPI process renders Jinja2 pages; one SQLite file holds ten tables of facts: properties, units, occupants, assets, services, work orders, visitors, meters, readings and events (the activity log). Users and invites sit alongside. JavaScript is used only for the assistant drawer and to filter unit and asset choices on the work-order form.

The four rules

  1. Derived, never stored. Vacancy, SLA state, next service and consumption are functions of facts, evaluated at read time.
  2. The assistant degrades honestly. Provider order: Anthropic (official SDK, structured JSON output) → OpenRouter → deterministic heuristic. It never raises; the badge reports the provider.
  3. Residents never need an account. Two public route families, both token-checked.
  4. Everything exports. CSV downloads call the same functions as the pages.

Quality

39 automated tests cover each acceptance criterion (schema, seed determinism, lifecycle edges, SLA arithmetic with holds, triage accuracy on labelled English and Hinglish messages, QR decoding, role permissions, API tokens). A headless browser walk visits every page in light and dark themes at three widths and fails on any console error, failed request or horizontal overflow.

11. Configuration

VariableMeaning
KEYSTONE_DBPath of the SQLite file (default keystone.db beside the app).
KEYSTONE_SEED=1Seed the synthetic demo into an empty database.
KEYSTONE_HOMEWhere the dashboard lives: / on site, /desk on the twin.
KEYSTONE_BASE_URLPublic base URL used in QR posters, resident and invite links.
SESSION_SECRETSigns sessions, tracking links and guest logins.
FEED_TOKENToken for the JSON API.
ANTHROPIC_API_KEY / OPENROUTER_API_KEYOptional; switch the assistant to a model.
uv venv .venv && uv pip install -r requirements.txt
KEYSTONE_SEED=1 .venv/bin/uvicorn app.main:app --port 8381

12. API reference

Read-only JSON. Pass the token as ?token=… or Authorization: Bearer …; without it the reply is 401 {"error": "unauthorized"}.

EndpointReturns
GET /healthzPublic. ok, counts, AI provider.
GET /api/v1/propertiesEach property with units, occupied, open work, SLA breaches, overdue service, kWh per 1,000 sq ft (4 weeks).
GET /api/v1/work?status=&property=Work orders with sla_due and sla_breached computed at request time. status=active means all open states.
GET /api/v1/readings?property=Every meter reading with its property, meter kind and label.
curl -s "https://keystone.ajaykongala.online/api/v1/work?status=active&token=$FEED_TOKEN" | jq '.work_orders[] | select(.sla_breached)'

Signed-in JSON helpers used by the assistant: POST /copilot/triage, GET /copilot/plan, GET /copilot/brief/{property_id}.

13. Known limits

  • The hosted twin's data lives in temporary storage per server instance and is rebuilt from the seed on a cold start. A request made from a resident link can land on an instance that later restarts, so its tracking page may stop resolving. The on-site lane keeps everything in one durable file.
  • No email or SMS notifications yet: residents follow their tracking link, staff watch the board.
  • Meter readings are entered by hand; live BMS ingest is on the roadmap. So are dues billing with UPI, CSV import, HVAC advice and ESG reports.
  • No file uploads (photos of a leak, invoices) yet.