Skip to content
VietGara Docs

RELEASE PLAN — PHASE 3

VietGara — Terminology: account → user

Version 3.0 — October 9, 2026 · Cloud: Google Cloud Platform (GCP) · Backend: Go

1. Introduction

The word account currently means three things: the person who signs in, the owner who holds the subscription (“one account, many garages”), and loosely a billing entity. Phase 3 fixes the vocabulary:

TermMeaning
UserA person who signs in to any VietGara app: owner, staff, customer with an app, platform admin or admin staff
OwnerA user who owns garages; the subscription belongs to the owner user
StaffA user’s membership of one garage, with staff groups and roles
CustomerA garage-owned profile of a vehicle owner. It needs no user; it may be linked to one (Release 5.1)
SupplierA garage-owned record of a business that sells parts to the garage. It is not a customer; a user link and portal come in Phase 17
Supplier userA user linked to a supplier of a garage (Phase 17). Works in the supplier portal; neither a customer nor staff
InsurerA garage-owned record of an insurance company, in the Insurance module (Phase 17). It is neither a customer nor a supplier
Platform admin / admin staffUsers holding platform permissions (Phase 8)

“Account” stays only where it is ordinary English: My account (a user’s own settings page), bank account, Google account, provider account.

Doing this first is cheapest. No real tenant exists, so no data has to be migrated, and Phase 4 (Quality Foundation) builds its test data and fixtures with the final names instead of renaming them later.

2. Overview of the 2 Releases

ReleaseNameMain ModulesDemoable Value
3.0Backend, Database & ContractsIdentity and every module with account_id, proto, eventsThe backend, database and API speak only of users
3.1Clients & DocumentsWeb consoles, Flutter core package and apps, docsEvery client and document uses the new vocabulary; all clients sign in against staging

3. Release Details

Release 3.0 — Backend, Database & Contracts

  • Database. Because the project is in development, the original migrations are edited in place (the convention of Database Design Section 1.1) and make db-reset rebuilds the local database; the staging database is dropped and recreated.
    • accounts becomes users (migration 000001); every account_id / *_account_id column becomes user_id / *_user_id; platform_admins.user_id, notification_log.user_id, outbox_events.user_id, the audit log’s actor, and the owner column of garages and subscriptions.
    • The RLS session variable app.current_account_id becomes app.current_user_id, together with its helper functions, policies, indexes and comments.
    • user is a reserved word in PostgreSQL, so the table is users and no column is named user.
  • Proto and REST. Message Account becomes User; fields account_id / accountId become user_id / userId; the session answer carries user. The OpenAPI document is regenerated. There is no dual account field: the clients change in the same sweep.
  • Events. Event types and payload fields follow (account.email_verified becomes user.email_verified; account_id becomes user_id). Topic names (vietgara.identity.events) are unchanged. The Kafka topics of dev and staging are recreated.
  • Tokens and configuration. Custom claims are renamed; TEST_ACCOUNTS_EMAIL_DOMAIN becomes TEST_USERS_EMAIL_DOMAIN; storage keys planned as accounts/{accountId}/… become users/{userId}/….
  • Migration freeze rule. Editing migrations in place is allowed only while no non-test tenant exists. From the first real tenant, migrations are forward-only. This rule is recorded in the Database Design and in the Git Strategy.
  • Definition of Done: the backend builds and all unit, integration and blackbox tests pass with the new names; a search for account in the backend and proto finds only the allowed phrases; the OpenAPI document and generated clients are regenerated.

Release 3.1 — Clients & Documents

  • Web consoles. Generated API types, hooks, i18n strings (Vietnamese and English) and routes in vietgara-owner-web, vietgara-admin-web and the shared UI kit.
  • Flutter. vietgara_core models, storage keys and error handling, then a new core version adopted by the owner, admin, technician and customer apps. The apps are rebuilt; no store build exists to keep compatible.
  • UI copy. “User” replaces “account” in admin and staff contexts. The page where a person edits their own profile keeps the name My account.
  • Documents. Every document in this repository, the E2E data and the glossary use the new terms; this repository’s rename is done in the same pull request series.
  • Reset. The staging database is wiped and the test accounts are recreated after the deployment; anyone testing on staging re-registers.
  • Definition of Done: all six clients sign in, switch garage and run the Quote → Repair Order → Settlement flow against the renamed staging; no user-facing text says “account” where it means a person who signs in.

4. Dependency Diagram

flowchart TD
  P2(["Phase 2 complete"]) --> R30["Release 3.0<br/>Backend, DB, contracts"]
  R30 --> R31["Release 3.1<br/>Clients & documents"]
  R31 --> DONE(["Phase 3 complete"])

Releases 3.0 and 3.1 ship together: branches in every repository are merged the same day and staging is reset once. The phase is small on purpose, so that nothing built afterwards has to be renamed.