Build and operate Zealix safely

Overview

Zealix is an AI-powered restaurant management platform built to help restaurant teams grow revenue and operate efficiently. It combines three core experiences:

• A public marketing site for discovery, product education, and lead capture.
• A content and support admin for managing pages, FAQs, blog posts, customer requests, and settings.
• Zea, an AI sales assistant that answers product questions, understands intent, and routes qualified leads.

The application runs on Next.js 16 and React 19. AWS provides compute, PostgreSQL, object storage, transactional email, secrets, and managed foundation models.

Local setup

Use Node.js with npm. The repository includes a lockfile and does not declare another package manager.

git clone git@github.com:cesarfrancots/ZealixLanding.git
cd ZealixLanding
npm ci
cp .env.example .env.local
npm run dev

The development server starts at http://localhost:3000. Keep local credentials in .env.local; never commit them.

Environment variables

.env.example is the configuration inventory. Coolify owns deployed environment variables, while AWS Secrets Manager stores secrets that should not live in repository or container metadata.

Architecture

Zealix is a single Next.js application with clear service boundaries. App Router pages and route handlers run on Coolify-managed containers; external state stays in AWS-managed services.

Authentication

Better Auth manages sessions, email verification, password reset, and role checks. Preserve trusted-origin validation and authorize every admin or customer operation on the server. UI visibility is never an authorization boundary.

Database & migrations

PostgreSQL on Amazon RDS is the source of truth. Runtime queries use parameterized SQL through pg. Applied migrations are checksum-tracked: add a new numbered migration instead of editing an existing one.

DATABASE_URL='postgresql://…' npm run db:migrate
DATABASE_URL='postgresql://…' npm run db:bootstrap-admin
DATABASE_URL='postgresql://…' npm run db:seed-knowledge

AI & Bedrock

Zea uses Amazon Nova for conversation and Titan embeddings for retrieval. Bundled Markdown knowledge provides a controlled fallback when vector search is unavailable. Answers must not invent prices, integrations, or operational guarantees.

Storage & uploads

Amazon S3 stores uploads privately by default. Validate filenames, content types, and object keys at the boundary. Serve private content with short-lived signed URLs and reserve CloudFront public delivery for explicitly approved prefixes.

Email

Amazon SES delivers account and support messages. Staging must never send to real customer lists: use test recipients or suppress delivery at the environment boundary.

Environment model

Production and staging share an EC2 host, but not mutable data, credentials, origins, or integration behavior.

Deployment flow

Changes move through pull requests and automated checks before they reach either persistent environment.

1. 1
   Feature branch

   Develop in an isolated worktree from fresh origin/master.

2. 2
   Staging

   Merge a reviewed PR into staging and validate the deployment.

3. 3
   Production

   Promote the verified commit to master through a second PR.

Rollback

Revert the failing commit through Git and redeploy the last known-good version in Coolify. Database migrations require a documented forward fix or an intentionally designed down migration; never improvise a destructive rollback against customer data.

Operations

Incident response

1. Protect customer data and contain the affected environment.
2. Capture timestamps, logs, deploy version, and observed impact.
3. Roll back application code when safe; preserve forensic evidence.
4. Document root cause, recovery, and a concrete prevention action.

Agent guidelines

Agents should make the smallest safe change, preserve user work, and leave evidence that the result works.

• Read AGENTS.md before editing and reuse existing patterns.
• Work in an isolated worktree on a codex/ branch; ship through a pull request.
• Never expose secrets or run production migrations as a routine check.
• Run TypeScript, lint, offline tests, and a production build before handoff.