AutoReview turns incoming reviews into grounded, brand-consistent reply drafts and routes every sensitive decision through a deterministic approval workflow.
Executable pilot · Multi-tenant by design · Automation disabled by default
Responding to customer reviews well requires speed, context, a consistent voice, and careful handling of sensitive situations. AutoReview automates preparation—not accountability.
The AI model can draft a response, identify risks, and cite the approved knowledge it used. It cannot access Google credentials, query the database directly, enable automation, or publish a response. Authorization and publication remain under application control.
Google review
→ Pub/Sub event
→ canonical review retrieval
→ approved business knowledge + AI drafting
→ independent validation and risk controls
→ approval, revision, rejection, or scheduled delivery
→ Google publication
→ reconciliation and audit
- Web and mobile inboxes for reviews requiring attention.
- Reply drafts generated in the language of the original review.
- Approve, edit, reject, or request a revised draft.
- Natural-language revision instructions such as “make it shorter and more empathetic.”
- Optimistic concurrency control prevents two users from publishing competing replies.
- The canonical Google review is retrieved again immediately before publication.
- Tenant- and location-specific business profiles.
- Brand voice, supported languages, services, hours, contact details, and FAQs.
- Escalation rules for complaints, refunds, and sensitive topics.
- Versioned sources with
draft,approved, andretiredlifecycle states. - Hybrid full-text and vector retrieval using PostgreSQL and
pgvector. - Only approved, currently valid sources may influence a reply.
- Human edits contribute to evaluation data; they never modify knowledge automatically.
- Rules scoped by location, rating, language, review text, category, and delay.
- A minimum of 20 manual reviews before a location becomes eligible for automation.
- A default 10-minute cancellation window before scheduled publication.
- Daily publication limits and a global kill switch.
- Non-bypassable hard stops for legal threats, health incidents, discrimination, fraud, refunds, chargebacks, personal data, employee allegations, and violent language.
- Push notifications never contain review text.
- Notifications deep-link to an authenticated screen; approval never happens inside the notification.
- Idempotent event processing and publication attempts.
- Controlled retries, dead-letter handling, and final-state reconciliation.
- Append-only audit records for actor, decision, model, provider, prompt version, and knowledge version.
- Scheduled removal of temporary Google content within the required retention window.
flowchart LR
GBP[Google Business Profile] --> PS[Pub/Sub]
PS --> W[Cloud Run worker]
W --> API[NestJS API]
WEB[Next.js dashboard] --> API
APP[Expo mobile app] --> API
API --> DB[(Cloud SQL PostgreSQL + pgvector)]
API --> AI[OpenRouter]
API --> TASKS[Cloud Tasks]
TASKS --> W
API --> PUSH[Expo Push]
API --> GBP
| Layer | Technology | Responsibility |
|---|---|---|
| Dashboard | Next.js 16, React 19 | Inbox, knowledge, rules, team, and audit |
| Mobile | Expo 57, React Native 0.86 | Push-driven review and approval workflow |
| API | NestJS 12, Fastify 5 | Authentication, authorization, workflow, and OpenAPI |
| Worker | Node.js, Fastify | Pub/Sub ingestion, Cloud Tasks, retries, and retention |
| Domain | TypeScript, Zod | State machine, hard stops, contracts, and validation |
| Data | PostgreSQL 17, Drizzle, pgvector | Tenant isolation, knowledge retrieval, and audit |
| AI | OpenRouter, pinned DeepSeek snapshot | Structured drafting without tools or data access |
| Infrastructure | Google Cloud, Terraform | Cloud Run, Cloud SQL, Pub/Sub, Tasks, KMS, and secrets |
The configured model is the immutable deepseek/deepseek-v4-pro-0813 snapshot. Requests use Structured Outputs, a provider allowlist, data_collection: "deny", and Zero Data Retention routing. The model returns a structured ReplyDraft; the deterministic policy engine alone decides whether the workflow may proceed.
stateDiagram-v2
[*] --> received
received --> generating
generating --> pending_approval
generating --> scheduled_auto
generating --> needs_attention
pending_approval --> publishing: approve
pending_approval --> rejected: reject
scheduled_auto --> pending_approval: cancel automation
scheduled_auto --> publishing: cancellation window expires
publishing --> published
publishing --> needs_attention: terminal failure
Every mutation includes an expectedVersion. Stale commands return 409 version_conflict. Before publication, the API retrieves the canonical review again. If the review changed or already has a reply, the draft is invalidated and returned for reassessment.
This repository contains an end-to-end pilot that runs with simulated data, plus adapters and infrastructure boundaries for real services.
| Capability | Status |
|---|---|
| Responsive operations dashboard | Implemented |
| iOS and Android companion app | Implemented; platform bundles verified |
| Approval workflow and hard stops | Implemented and tested |
| Real and simulated Google adapters | Implemented |
| Structured OpenRouter provider | Implemented |
| PostgreSQL schema, RLS, and migrations | Implemented |
| Google Cloud Terraform stack | Implemented and validated |
| Pilot against a real Google location | External Google approval and credentials required |
| PostgreSQL-backed API repository | Required before production |
| Physical-device push and store releases | Verification required |
| Commercial multi-tenant SaaS operation | Written Google confirmation required |
Important
AutoReview is not currently represented as production-ready. Local development uses simulated authentication, Google, AI, and scheduling by default. No real review is published in the development workflow.
- Node.js 24 LTS
- pnpm 11
- Docker Desktop, when running PostgreSQL locally
git clone https://github.com/DevvoLazza/AutoReview.git
Set-Location AutoReview
Copy-Item .env.example .env
pnpm install
pnpm devLocal services:
| Service | URL |
|---|---|
| Dashboard | http://localhost:3000 |
| API | http://localhost:4100/v1 |
| Swagger UI | http://localhost:4100/docs |
| OpenAPI document | http://localhost:4100/openapi.json |
| Worker | http://localhost:4200 |
The dashboard and mobile app fall back to demonstration data when the API is unavailable. To simulate a new review while the API is running:
Invoke-RestMethod -Method Post `
-Uri http://localhost:4100/v1/webhooks/google-business/demodocker compose up -d postgres
pnpm db:migrateAvailable environment variables are documented in .env.example. Safe local defaults are explicit:
AUTH_MODE=demo
AI_MODE=mock
GOOGLE_MODE=mock
TASKS_MODE=mockProduction credentials must be supplied through Secret Manager. Google refresh tokens must be encrypted with Cloud KMS before persistence. Never commit credentials, tokens, .env files, or real review data.
pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm audit --prodThe automated suite covers:
- state-machine transitions and version conflicts;
- hard stops and automation eligibility;
ReplyDraftvalidation and OpenRouter request controls;- Pub/Sub redelivery and event deduplication;
- draft generation, approval, and publication API behavior;
- web, Android, and iOS bundles.
GitHub Actions runs linting, type checking, tests, production builds, and Terraform formatting and validation with a required lockfile.
AutoReview/
├── apps/
│ ├── api/ REST API, OAuth, authorization, and workflow
│ ├── worker/ Pub/Sub, Cloud Tasks, retries, and retention
│ ├── web/ Next.js operations dashboard
│ └── mobile/ Expo iOS and Android app
├── packages/
│ ├── contracts/ shared Zod contracts
│ ├── core/ domain, AI, Google, and policy engine
│ └── database/ Drizzle, PostgreSQL, RLS, and pgvector
├── infra/terraform/ Google Cloud infrastructure
├── docs/ architecture, API, security, and go-live guidance
└── .github/workflows/ continuous integration
- Architecture and trust boundaries
- API endpoints and contracts
- Engineering security model
- Security policy and vulnerability reporting
- Google go-live checklist
- Obtain access to the Google Business Profile APIs.
- Configure OAuth, Identity Platform, and enforced MFA.
- Replace the in-memory API store with the transactional PostgreSQL repository.
- Enable KMS encryption for Google refresh tokens.
- Configure OpenRouter and verify provider, ZDR, and processing-location requirements.
- Apply migrations and Terraform in a dedicated Google Cloud project.
- Exercise Pub/Sub, push delivery, OAuth revocation, and publication against one real location with automation disabled.
- Complete physical-device testing before TestFlight or Play Internal Testing.
- Complete privacy, DPA/SCC, incident-response, backup-restore, and store-listing work.
Google Business Profile does not provide a complete sandbox. The simulated adapter makes local development and CI deterministic, but it does not replace the controlled real-location pilot.
Development happens on dev; main represents the synchronized release branch. Before proposing a change, run:
pnpm lint
pnpm typecheck
pnpm test
pnpm buildKeep commits focused, reviewable, and independently meaningful. Do not commit secrets, .env files, personal data, or production review content.
Licensed under the MIT License. Copyright © 2026 Lazzaro Davide.