ElectroUchet

ElectroUchet is an offline-first workflow for collecting and reconciling common-area electricity meter readings. It helps a small utility or property-management team replace paper routes and fragile spreadsheets with an auditable field-to-office process.

Built for the OpenAI Build Week — Work & Productivity track with Codex and GPT-5.6.

Why it matters

Meter readers often work in basements and utility rooms with unreliable connectivity. ElectroUchet keeps the field workflow usable without internet access, synchronizes safely when the internal network returns, and gives the administrator one place to compare primary readings with utility reference data.

End-to-end workflow

1. An administrator signs in with a username and password.
2. The administrator creates a field employee and assigns customer accounts.
3. The employee opens /mobile and signs in with an employee ID and four-digit PIN.
4. Assigned addresses and meters are cached on the device.
5. Readings and optional meter photos are stored locally while offline.
6. The queue synchronizes automatically when the internal network returns.
7. Duplicate delivery is safe: the server uses a device ID and client-generated record ID for idempotency.
8. The administrator reviews readings, discrepancies, tasks, imports, and the monthly Excel report.

Monthly legacy .XLS registers from the utility are imported without conversion. ElectroUchet detects the account group and period from the filename, preserves rows with missing readings, calculates consumption from current and previous values, and keeps the original source filename for auditability.

Build Week extension

The initial prototype existed before the final hackathon implementation. During the submission period, Codex with GPT-5.6 was used to turn it into a working, testable product by adding:

• the FastAPI/SQLite production backend and role-separated authentication;
• an offline-capable field PWA with durable IndexedDB queueing;
• automatic retry and idempotent batch synchronization;
• camera/photo handoff after a reading is accepted by the server;
• employee creation, activation, and account assignment in the admin panel;
• a synthetic, one-command judge demo environment;
• automated security, authorization, synchronization, import, and build tests.

See BUILD_WEEK.md for the contribution boundary and evidence checklist.

Russian documentation: README_RU.md.

Submission materials: English video script, Russian video script, English checklist, and Russian checklist.

Free demo hosting notes: English / Russian guide.

Judge demo

Prerequisites: Docker Desktop or Docker Engine with Compose.

docker compose -f compose.demo.yml up --build

Open:

• Admin panel: http://localhost:13000
• Field mode: http://localhost:13000/mobile
• API documentation: http://localhost:13000/docs

Synthetic demo credentials:

• Administrator: demo-admin / demo-electro-2026
• Field employee: ID 2 / PIN 2468

The demo database contains only fictional addresses, meters, readings, and tasks. Stop it with:

docker compose -f compose.demo.yml down

The demo database is ephemeral. Recreating the stack resets all changes:

docker compose -f compose.demo.yml down
docker compose -f compose.demo.yml up -d --build

Sample files for the two supported import flows are included in backend/demo_assets/imports/. They contain synthetic account 139 data only.

Test the offline flow

1. Sign in to Field Mode while online.
2. In browser developer tools, switch the network to Offline.
3. Add a reading, optionally with a photo. The queue counter increases.
4. Restore the network. The queue synchronizes automatically.
5. Sign in to the admin panel and open Readings to verify the result.
6. Submit the same client record again through the API to observe an idempotent duplicate result rather than a second reading.

Architecture

Phone / PWA                       Internal server
┌──────────────────────┐          ┌────────────────────────────┐
│ PIN sign-in          │          │ FastAPI                    │
│ Cached assignments   │  HTTPS   │ Role and account checks    │
│ IndexedDB queue      ├─────────►│ Idempotent batch sync      │
│ Optional photo       │          │ SQLite + protected photos  │
└──────────────────────┘          └─────────────┬──────────────┘
                                               │
                                   ┌───────────▼───────────────┐
                                   │ Admin web panel           │
                                   │ Reconciliation + reports  │
                                   └───────────────────────────┘

• Web: React 19, TypeScript, vinext/Vite
• API: FastAPI, SQLAlchemy, Pydantic
• Storage: SQLite, Alembic, filesystem photo storage
• Reports: openpyxl
• Deployment: Docker Compose

The production design remains offline-first: synchronization happens only through the organization's internal network. OpenAI is used as the engineering environment through Codex/GPT-5.6, not as a runtime dependency, so field data is not sent to an external AI API.

Local development

Backend:

cd backend
py -m venv .venv
.venv\Scripts\pip.exe install -r requirements.txt
Copy-Item .env.example .env
.venv\Scripts\python.exe -m alembic upgrade head
.venv\Scripts\python.exe -m uvicorn app.main:app --reload --port 8100

Web:

npm ci
npm run dev

Verification

cd backend
.venv\Scripts\python.exe -m pytest tests -q
cd ..
npm test
npm run lint
docker compose -f compose.demo.yml config

Security notes

• Web administrators use a username and password; field employees use ID + PIN.
• Passwords and PINs are PBKDF2-SHA256 hashes with individual salts.
• Five failed PIN attempts trigger a 15-minute lockout.
• Session tokens are stored as hashes and can be revoked.
• Account assignments are enforced by the server, not only hidden in the UI.
• Secrets and real datasets are excluded from source control.
• Demo credentials are intentionally limited to the isolated synthetic demo stack.

License

MIT — see LICENSE.