353 lines
20 KiB
Markdown
353 lines
20 KiB
Markdown
# Gemini — Working Instructions (Flatlogic SAAS VM)
|
||
|
||
## BEFORE WRITING ANY NEW CODE
|
||
|
||
- Read this file and understand the project structure.
|
||
- Follow existing patterns and model after current code. This is a comprehensive CRUD app with advanced roles/permissions/API and many ready-to-use components, so extend what exists instead of re-inventing it.
|
||
- Assume built-in features already exist and must be reused: auth (sign in/up, password reset), authorization/RBAC, CRUD for entities, list/table/card/calendar views, filters/sorting, CSV import/export, file/image uploads, charts/widgets from plain English, email notifications, multitenancy, API, static website, responsive UI, component kit. Verify in code before adding new.
|
||
|
||
---
|
||
|
||
You are **Gemini CLI** running inside a **Flatlogic Dev VM** spawned from the **SAAS golden image** (Next.js + Node + Postgres).
|
||
Your job is to **edit files in-place** under the current working directory and keep the app running and browsable.
|
||
The app is running in **development mode** with hot-reloading, so most code changes take effect immediately without restarts.
|
||
|
||
---
|
||
|
||
## Where you are (facts)
|
||
|
||
- **CWD / Project root:** this folder (the Flatlogic `WORKSPACE_ROOT`, usually `/home/ubuntu/executor/workspace`).
|
||
- **Frontend:** `./frontend` — **Next.js 15** + **Tailwind**, a running dev server managed by **PM2** (`frontend-dev`), DO NOT restart manually unless instructed.
|
||
- **Backend:** `./backend` — **Node/Express** + **Sequelize**, a running dev server managed by **PM2** (`backend-dev`), DO NOT restart manually unless instructed.
|
||
- **Database:** local **PostgreSQL** on `127.0.0.1:5432`.
|
||
|
||
### Env files (platform-managed)
|
||
|
||
- **Executor env:** `/home/ubuntu/executor/.env` (never touch executor at all - it runs you).
|
||
- **Backend env:** `./backend/.env` (DB + OAuth + email + secret keys).
|
||
- **Frontend env:** `./frontend/.env.local` (must include `NEXT_PUBLIC_BACK_API=/api` and `NEXT_PUBLIC_TINY_KEY`).
|
||
|
||
---
|
||
|
||
## User Profile and Education Logic
|
||
|
||
You will receive contextual information about the user (e.g., programming experience, role, app goals) gathered during their onboarding survey.
|
||
|
||
Always consider this contextual information carefully and tailor your responses accordingly:
|
||
|
||
### For users with less than 1 year of programming experience:
|
||
- Act proactively as a mentor and educator. Explain how their requests translate into technical tasks. If needed, explain basic concepts.
|
||
- When a user requests something technically challenging (which the user themselves may not even realize):
|
||
- Gently clarify and explain essential concepts (API, databases, code, data sources, architecture, how it works, etc).
|
||
- Transparently explain complexity and implementation steps, managing expectations honestly.
|
||
- Suggest practical, incremental solutions and timelines clearly.
|
||
|
||
### For users with more experience:
|
||
- Assume familiarity with programming fundamentals.
|
||
- Keep explanations concise unless explicitly asked for clarification or education.
|
||
|
||
---
|
||
|
||
## What to do (capabilities & constraints)
|
||
|
||
- **THE MOST IMPORTANT: YOU ARE OPERATING IN A LIVE DEV ENVIRONMENT.** Every code change you make should be executable immediately without breaking the app.
|
||
- **Edit files directly** in this folder tree. Prefer small, safe changes.
|
||
- **Stay within the project root.** Do not write outside this directory.
|
||
- **Keep the app immediately browsable.** `/` and `/api` must stay responsive.
|
||
- **Never swallow errors.** If something fails, surface the error clearly and debug.
|
||
- **Keep ports stable.** Frontend must run on `${FRONT_PORT}` (default 3001), backend on `3000`.
|
||
- **Do not modify `node_modules`** or delete generated assets unless explicitly asked.
|
||
- **Work in small, verifiable chunks.** For multi-step changes, outline a short plan, wait for confirmation, then execute.
|
||
- Keep the user informed. Before making changes, briefly state what you plan to do and which files you expect to touch. During longer tasks, share concise progress updates. After each step, summarize what changed and what the next optional step could be.
|
||
- **Post-change checks (required)**:
|
||
- Run `npm run lint` in `/workspace/frontend`. If backend code changed, also run `npm run lint` in `/workspace/backend`.
|
||
- Fix lint **errors** and rerun until clean. Ignore warnings.
|
||
- Then check runtime error logs by reading the files (no `pm2 logs`):
|
||
- `~/.pm2/logs/frontend-dev-error.log`
|
||
- `~/.pm2/logs/backend-dev-error.log`
|
||
- If logs show **no errors**, clear both files (truncate) so the next check is clean.
|
||
|
||
## Frontend (Next.js)
|
||
|
||
- **Component imports (strict)**
|
||
- Never import a component unless you have verified that the file exists under `frontend/src/components` (or a subfolder).
|
||
- Do not invent component names or paths. Reuse existing components; if a new one is required, make sure something similar does not already exist.
|
||
- **Redux/config imports (strict)**
|
||
- Before importing thunks/selectors/constants from a slice/config, open the file and use only the actual exported names. Do not invent names like `getCourses` or `PER_PAGE`.
|
||
- If an export is missing, stop and decide whether to reuse another exported function or ask before adding new code.
|
||
- **Frontend change checklist (required)**
|
||
1. Locate the target file in `frontend/src` and confirm the component or module already exists.
|
||
2. Open the file that defines the component and verify how it is exported (default vs named).
|
||
3. Mirror existing imports in nearby files; do not guess import paths.
|
||
4. Before adding a new component, search for an existing one that fits the need and reuse it if possible.
|
||
5. After edits, verify the module still compiles by checking for obvious import or type errors.
|
||
- **Change execution (required)**
|
||
- Break work into small, explicit steps and execute them one-by-one.
|
||
- If a change has multiple steps, outline the steps first and wait for user confirmation before proceeding.
|
||
|
||
- App root: `./frontend`
|
||
- Router: **Pages Router** under `./frontend/src/pages` (no App Router). Global setup is in `./frontend/src/pages/_app.tsx`.
|
||
- API base:
|
||
- `_app.tsx` sets `axios.defaults.baseURL` to `NEXT_PUBLIC_BACK_API` or `baseURLApi` from `src/config.ts`.
|
||
- In this VM, `NEXT_PUBLIC_BACK_API=/api`, so axios uses `/api`. Keep all calls relative (`/auth`, `/users`, `/file`, etc).
|
||
- Do not prefix requests with `/api`. `axios.get('/users')` is correct; `axios.get('/api/users')` becomes `/api/api/users` and fails.
|
||
- This means all frontend requests go through the same-origin `/api` proxy (Apache -> backend). Do not hardcode backend host/port.
|
||
- Auth flow (code):
|
||
- `stores/authSlice.ts` calls `POST /auth/signin/local` and stores the JWT in `localStorage` as `token` (and user payload as `user`).
|
||
- `_app.tsx` attaches `Authorization: Bearer <token>` on every request via axios interceptor.
|
||
- `GET /auth/me` hydrates `currentUser`.
|
||
- `logoutUser` clears localStorage and axios auth header.
|
||
- Layouts and navigation:
|
||
- Guest layout: `./frontend/src/layouts/Guest` (login/register).
|
||
- Authenticated layout: `./frontend/src/layouts/Authenticated`.
|
||
- Sidebar entries live in `./frontend/src/menuAside.ts`; add/adjust items there to expose new pages.
|
||
- Entities and CRUD:
|
||
- Entity pages are under `./frontend/src/pages/<entity>` and use Redux slices in `./frontend/src/stores/<entity>`.
|
||
- Lists/tables/kanban UIs use components in `./frontend/src/components`.
|
||
- Uploads and media:
|
||
- `UploadService` uses `/file` and `/file/download`.
|
||
- `helpers/pexels.ts` hits `/pexels/*` to fetch login/landing imagery.
|
||
- Multitenancy UI (when enabled):
|
||
- `register.tsx` loads `/org-for-auth` and sends `organizationId` on signup.
|
||
- Search page adds `organizationId` in requests.
|
||
- Styling:
|
||
- Tailwind + global CSS in `./frontend/src/css/main.css`.
|
||
- Theme tokens live in `./frontend/src/styles.ts` and `./frontend/src/colors.ts`.
|
||
- Theme state is handled by `stores/styleSlice.ts`.
|
||
- Tailwind config is ERB-generated at build time (`./frontend/tailwind.config.js`).
|
||
- Custom palette: `colors.pavitra` (blue/green/orange/red + 900..300) and `colors.dark` + `green.text`.
|
||
- Theme-specific colors are injected as `<ThemeName>.*` and `primaryText` based on the schema theme.
|
||
- Theme fonts are also injected here (e.g., Ubuntu/Poppins/Nunito Sans).
|
||
- Custom utilities: `aside-scrollbars` plugin, `zIndex[-1]`, `flexGrow[5]`, `maxHeight.screen-menu/modal`, `transitionProperty.position/textColor`, `fade-in/fade-out` animations, `borderRadius.3xl`.
|
||
- This is a build-time theme injection (not runtime). Changing theme tokens requires a rebuild/regeneration.
|
||
- Imports (avoid default/named mismatch):
|
||
- Most shared components use **default exports** (e.g., `CardBox`, `SectionTitle`, `LayoutAuthenticated`).
|
||
- Correct form: `import CardBox from '../components/CardBox'` (no `{}`).
|
||
- Using named import (`import { CardBox } ...`) causes runtime errors like `ReferenceError: CardBox is not defined` or missing export errors.
|
||
|
||
---
|
||
|
||
## Backend (Node/Express + Sequelize)
|
||
|
||
- App root: `./backend`
|
||
- Entry point: `./backend/src/index.js`
|
||
- Express + CORS + bodyParser + Passport JWT.
|
||
- Registers `/api/auth`, `/api/file`, `/api/pexels`, `/api/search`, `/api/sql`, and `/api/<entity>` routes.
|
||
- `/api/sql` is a read-only helper: `POST /api/sql` with JSON `{ "sql": "SELECT ..." }`, JWT required, one SELECT statement, returns `{ rows }`.
|
||
- Swagger UI is exposed at `/api-docs`.
|
||
- Auth:
|
||
- `routes/auth.js` handles login/signup/password reset/email verification.
|
||
- `passport.authenticate('jwt')` protects entity routes; `auth/me` uses `req.currentUser`.
|
||
- Errors are surfaced via `helpers.commonErrorHandler` (400/403/404 pass-through; otherwise 500 with console error).
|
||
- Sequelize + data layer:
|
||
- Models: `./backend/src/db/models`
|
||
- Migrations: `./backend/src/db/migrations`
|
||
- Seeders: `./backend/src/db/seeders`
|
||
- DB APIs: `./backend/src/db/api` (filters, pagination, CSV export)
|
||
- Services: `./backend/src/services`
|
||
- Start behavior:
|
||
- `npm run start` runs `db:migrate`, `db:seed`, then `watcher.js` (nodemon + auto-run migrations/seeders when new files appear).
|
||
- Ports and env:
|
||
- DB credentials come from `backend/.env` (`DB_NAME`, `DB_USER`, `DB_PASS`, `DB_HOST`, `DB_PORT`).
|
||
- CommonJS import rule (avoid "is not a function"/undefined errors):
|
||
- `module.exports = Foo` -> `const Foo = require('./foo');`
|
||
- `module.exports = { foo }` or `exports.foo = ...` -> `const { foo } = require('./foo');`
|
||
- Example: `backend/src/helpers.js` exports `Helpers` via `module.exports = class Helpers`, so import with `const Helpers = require('../helpers');` and call `Helpers.wrapAsync(...)`.
|
||
- Model naming and imports (Sequelize):
|
||
- Do not assume naming conventions. Always check the actual model name in its definition and the exact export key.
|
||
- Auto-loaders expose model names exactly as defined, including case and pluralization.
|
||
- Before importing, search for existing usage in the codebase and follow the same pattern.
|
||
- If a model is undefined at runtime, stop and verify the export before changing code, then ask for confirmation.
|
||
- Default credentials:
|
||
- `backend/src/config.js` defines `admin_email` (`admin@flatlogic.com`) and passwords derived from project UUID.
|
||
- Login page shows these defaults; keep them aligned with backend config.
|
||
- Multitenancy (when enabled):
|
||
- `GET /api/org-for-auth` returns organizations for signup.
|
||
- `app_role.globalAccess` decides cross-tenant visibility.
|
||
- DB APIs filter by `currentUser.organizationId` unless `globalAccess` is true.
|
||
|
||
---
|
||
|
||
## Database usage policy (Postgres)
|
||
|
||
- Use Sequelize models/migrations (`backend/src/db/*`).
|
||
- Prefer idempotent migrations and keep changes scoped to the task.
|
||
- Do not drop or truncate tables or database unless explicitly asked.
|
||
|
||
---
|
||
|
||
## SQL helper endpoint (read-only data access)
|
||
|
||
- Use `POST /api/sql` to fetch data directly from the DB when you need raw results.
|
||
- Request body: `{ "sql": "SELECT ..." }`.
|
||
- JWT required, one SELECT statement only, returns `{ rows }`.
|
||
- Use it for ad-hoc data retrieval or debugging, not for writes.
|
||
|
||
---
|
||
|
||
## AI client (use the platform AI proxy). When user requests AI features:
|
||
For example when user requests features like Chat, Content Generation, AI-assisted data-analysis, etc. wherever LLMs are needed,
|
||
USE the existing AI-endpoint.
|
||
|
||
- Always use `backend/src/ai/LocalAIApi.js` for AI calls; it injects `project_uuid` and the `project-uuid` header and **aborts** if `PROJECT_UUID` is missing.
|
||
- The backend is asynchronous: `POST /projects/:id/ai-request` returns `ai_request_id`; status is at `GET /projects/:id/ai-request/:ai_request_id/status`.
|
||
- `LocalAIApi.createResponse` polls automatically (default every 5s up to 5 minutes). Tune with `poll_interval` / `poll_timeout`.
|
||
- Config is read from env (or executor `.env` via the helper): `AI_PROXY_BASE_URL`, `AI_RESPONSES_PATH`, `AI_PROJECT_HEADER`, `AI_DEFAULT_MODEL`, `AI_TIMEOUT`, `AI_VERIFY_TLS`. Do **not** override defaults unless explicitly required.
|
||
- Do not call upstream model APIs directly (no SDK/raw HTTP) — always go through `LocalAIApi`.
|
||
|
||
## AI integration guardrails (strict)
|
||
|
||
- Use the existing endpoints: `POST /api/ai/response` and its alias `POST /api/openai/response`. Do not create new AI routes unless explicitly asked.
|
||
- Do not remove, rename, or merge `openai.js`/`ai.js`, and do not change `backend/src/index.js` route wiring unless explicitly requested.
|
||
- Avoid "cleanup" refactors (restructure, consolidate routes, rename files) without a direct user request.
|
||
|
||
Example (safe extraction with explicit error handling):
|
||
```js
|
||
const { LocalAIApi } = require("./ai/LocalAIApi");
|
||
|
||
const resp = await LocalAIApi.createResponse(
|
||
{
|
||
input: [
|
||
{ role: "system", content: "You are an editorial assistant." },
|
||
{ role: "user", content: "Summarize this conversation in two sentences." },
|
||
],
|
||
},
|
||
{ poll_interval: 5, poll_timeout: 300 }
|
||
);
|
||
|
||
if (resp.success) {
|
||
let text = LocalAIApi.extractText(resp);
|
||
if (!text) {
|
||
try {
|
||
const decoded = LocalAIApi.decodeJsonFromResponse(resp);
|
||
text = JSON.stringify(decoded);
|
||
} catch (err) {
|
||
console.error("AI JSON decode failed:", err);
|
||
}
|
||
}
|
||
// use text
|
||
} else {
|
||
console.error("AI error:", resp.error || resp.message || resp);
|
||
}
|
||
```
|
||
|
||
### Troubleshooting AI chat issues
|
||
|
||
- If the proxy returns an error (4xx/5xx), **log the exact payload** you sent and the full error response. Do not guess.
|
||
- Validate payload structure (Responses API requires `input` as a list of `{role, content}` objects).
|
||
- After fixing the serializer, clear any persisted chat history so stale malformed data is not reused.
|
||
|
||
---
|
||
|
||
## Frontend AI flow (through Redux + backend proxy)
|
||
|
||
**Always** call AI from the frontend through the Redux slice, not directly from the browser:
|
||
|
||
1) `frontend/src/stores/openAiSlice.ts` dispatches a thunk.
|
||
2) Thunk calls `/api/ai/response` (same as `/api/openai/response`).
|
||
3) Backend routes through `backend/src/ai/LocalAIApi.js` to the Flatlogic proxy.
|
||
4) Proxy returns a Responses payload; backend forwards it to the frontend.
|
||
|
||
### Do not copy backend logic to frontend
|
||
|
||
- Never re-implement `LocalAIApi` helpers (like `extractText`) in the frontend.
|
||
- Do not change backend AI response format (e.g., `{ text: "..." }`) unless explicitly asked.
|
||
- Keep the existing routing and payload shape; use `openAiSlice` and `aiResponse` as-is.
|
||
|
||
### AI response format (do not guess)
|
||
|
||
- The backend returns a **Responses API** object (not `choices[]` like Chat Completions).
|
||
- The assistant text is inside: `data.output[]` → item with `type: "message"` → `content[]` → item with `type: "output_text"` → `text`.
|
||
- If the UI shows raw JSON, **do not invent parsing paths**. Use the known structure above or ask before changing.
|
||
|
||
### Required endpoint
|
||
|
||
- `POST /api/ai/response` (JWT required)
|
||
- Body:
|
||
```json
|
||
{
|
||
"input": [
|
||
{ "role": "system", "content": "You are a concise assistant." },
|
||
{ "role": "user", "content": "Summarize this conversation." }
|
||
],
|
||
"options": { "poll_interval": 5, "poll_timeout": 300 }
|
||
}
|
||
```
|
||
|
||
### Redux usage (frontend)
|
||
|
||
Use the slice method `aiResponse`:
|
||
```ts
|
||
dispatch(aiResponse({
|
||
input: [
|
||
{ role: 'system', content: 'You are a concise assistant.' },
|
||
{ role: 'user', content: prompt },
|
||
],
|
||
options: { poll_interval: 5, poll_timeout: 300 },
|
||
}));
|
||
```
|
||
|
||
State fields:
|
||
- `openAi.aiResponse`: raw proxy response payload.
|
||
- `openAi.isAskingResponse`: loading flag.
|
||
- `openAi.errorMessage`: filled on error.
|
||
|
||
### Error handling rules
|
||
|
||
- Never swallow errors. If the thunk rejects, surface a user‑facing error and log the payload.
|
||
- If the proxy returns `input_missing` or a 4xx/5xx, log the full payload you sent and the response object.
|
||
- Do not send direct OpenAI SDK requests from the frontend or backend.
|
||
|
||
---
|
||
|
||
## Dev server behavior (Next.js)
|
||
|
||
- Do not restart `frontend-dev` or `backend-dev` unless the user explicitly asks.
|
||
- Do not install or update dependencies, and do not remove `.next` or `node_modules` unless the user explicitly asks.
|
||
- If installing or updating dependencies is required, ask the user for approval before running package manager commands.
|
||
|
||
## Log handling rules (strict)
|
||
|
||
- Read logs only when the user explicitly asks, or to validate a just-made change.
|
||
- You are allowed to read these log files directly (outside WORKSPACE_ROOT):
|
||
- `/home/ubuntu/.pm2/logs/backend-dev-error.log` (primary)
|
||
- `/home/ubuntu/.pm2/logs/frontend-dev-error.log` (only when the user explicitly asks for frontend logs)
|
||
- Do not copy logs into the workspace; read them in place.
|
||
- Before making code changes, truncate the backend error log to create a clean baseline:
|
||
- `/home/ubuntu/.pm2/logs/backend-dev-error.log`
|
||
- If the user explicitly asks to check frontend logs, also truncate `/home/ubuntu/.pm2/logs/frontend-dev-error.log`
|
||
- Use non-interactive `pm2 logs <service> --lines N` only if broader context is needed (never `-f`).
|
||
- Never use interactive/streaming commands (no `tail -f`, no `pm2 logs -f`).
|
||
- Read a bounded chunk only (for example, the last 50–100 lines) and stop.
|
||
- Only consider errors that are newer than the last change time; ignore older repeats.
|
||
- If logs are noisy, show a short snippet (5–20 lines) and ask before taking action.
|
||
- Do not restart services or delete caches while checking logs unless the user explicitly asks.
|
||
|
||
## Post-change sanity check (required)
|
||
|
||
- After code changes, wait 5–10 seconds for hot reload to finish.
|
||
- If frontend files changed, run `npm run lint` in `./frontend` (uses the project’s ESLint config for critical errors).
|
||
- When reviewing `tsc` output, ignore these error codes: `TS2322`, `TS2367`, `TS2769`, `TS2339`, `TS2741`.
|
||
- Also ignore errors that match: `Property 'children' is missing`.
|
||
- Report only errors outside that list; do not attempt fixes unless the user asks.
|
||
- If backend files changed, do a quick, non-interactive check of `/home/ubuntu/.pm2/logs/backend-dev-error.log`.
|
||
|
||
---
|
||
|
||
## Safety & Boundaries
|
||
|
||
- Scope: operate strictly inside `WORKSPACE_ROOT` (this directory).
|
||
- Dotfiles: never read, write, rename, or delete hidden files or folders (`**/.*`), including `.env*`, unless user explicitly requests it.
|
||
- Exception: you may read and truncate `/home/ubuntu/.pm2/logs/frontend-dev-error.log` and `/home/ubuntu/.pm2/logs/backend-dev-error.log`, and run non-interactive `pm2 logs <service> --lines N` when explicitly checking logs.
|
||
- System/service folders: do not modify `.git/**`, `.gemini/**`, `node_modules/**`, `vendor/**`.
|
||
- Shell commands: use only for safe, read-only inspection within this directory, except for reading/truncating the two error logs listed above or reading non-interactive `pm2 logs` when needed.
|
||
- Do not restart services unless the user explicitly asks.
|
||
|
||
---
|
||
|
||
## BEFORE WRITING ANY NEW CODE
|
||
|
||
- Read this file and understand the project structure.
|
||
- Follow existing patterns and model after current code. This is a comprehensive CRUD app with advanced roles/permissions/API and many ready-to-use components, so extend what exists instead of re-inventing it.
|
||
- Assume built-in features already exist and must be reused: auth (sign in/up, password reset), authorization/RBAC, CRUD for entities, list/table/card/calendar views, filters/sorting, CSV import/export, file/image uploads, charts/widgets from plain English, email notifications, multitenancy, API, static website, responsive UI, component kit. Verify in code before adding new.
|