index.tsx and place.tsx

.cursorrules

@@ -0,0 +1,305 @@
+# Cursor Rules - Group 1: Development Philosophy & Coding Conventions
+1. Overall Architecture & Structure:
+   - Enforce a clear separation of concerns between the backend and the frontend:
+     - **Backend**: Use Express for routing, Passport for authentication, and Swagger for API documentation. Organize code into modules such as routes, services, and helpers.
+       - **Example**:
+         - Routes: `src/routes/auth.js` for authentication routes.
+         - Services: `src/services/auth.js` for authentication logic.
+         - Helpers: `src/helpers/wrapAsync.js` for wrapping asynchronous functions.
+     - **Frontend**: Use Next.js with React and TypeScript. Structure components using functional components, hooks, and layouts.
+       - **Example**:
+         - Pages: `pages/index.tsx` for the main page.
+         - Components: `components/Header.tsx` for the header component.
+         - Layouts: `layouts/MainLayout.tsx` for common page layouts.
+   - Ensure that backend modules and frontend components are organized for reusability and maintainability:
+     - **Backend**: Separate business logic into services and use middleware for common tasks.
+     - **Frontend**: Use reusable components and hooks to manage state and lifecycle.
+
+2. Coding Style & Formatting:
+   - For the backend (JavaScript):
+       • Use ES6+ features (const/let, arrow functions) consistently.
+       • Follow Prettier and ESLint configurations (e.g., consistent 2-space indentation, semicolons, and single quotes).
+       • Maintain clear asynchronous patterns with helper wrappers (e.g., wrapAsync).
+         - **Example from auth.js**:
+           ```javascript
+           router.post('/signin/local', wrapAsync(async (req, res) => {
+             const payload = await AuthService.signin(req.body.email, req.body.password, req);
+             res.status(200).send(payload);
+           }));
+           ```
+      • Document API endpoints with inline Swagger comments to ensure API clarity and consistency.
+         - **Example**:
+           ```javascript
+           /**
+            * @swagger
+            * /api/auth/signin:
+            *   post:
+            *     summary: Sign in a user
+            *     responses:
+            *       200:
+            *         description: Successful login
+            */
+           ```
+   - For the frontend (TypeScript/React):
+       • Use functional components with strict typing and separation of concerns.
+         - **Example**:
+           ```typescript
+           const Button: React.FC<{ onClick: () => void }> = ({ onClick }) => (
+             <button onClick={onClick}>Click me</button>
+           );
+           ```
+       • Follow naming conventions: PascalCase for components and types/interfaces, camelCase for variables, hooks, and function names.
+         - **Example**:
+           ```typescript
+           const useCustomHook = () => {
+             const [state, setState] = useState(false);
+             return [state, setState];
+           };
+           ```
+       • Utilize hooks (useEffect, useState) to manage state and lifecycle in a clear and concise manner.
+         - **Example**:
+           ```typescript
+           useEffect(() => {
+             console.log('Component mounted');
+           }, []);
+           ```
+
+3. Code Quality & Best Practices:
+   - Ensure code modularity by splitting complex logic into smaller, testable units.
+     - **Example**: In `auth.js`, routes are separated from business logic, which is handled in `AuthService`.
+   - Write self-documenting code and add comments where the logic is non-trivial.
+     - **Example**: Use descriptive function and variable names in `auth.js`, and add comments for complex asynchronous operations.
+   - Embrace declarative programming and adhere to SOLID principles.
+     - **Example**: In service functions, ensure each function has a single responsibility and dependencies are injected rather than hardcoded.
+
+4. Consistency & Tools Integration:
+   - Leverage existing tools like Prettier and ESLint to automatically enforce style and formatting rules.
+     - **Example**: Use `.prettierrc` and `.eslintrc.cjs` for configuration in your project.
+   - Use TypeScript in the frontend to ensure type safety and catch errors early.
+     - **Example**: Define interfaces and types in your React components to enforce strict typing.
+   - Maintain uniformity in API design and error handling strategies.
+     - **Example**: Consistently use Passport for authentication and a common error handling middleware in `auth.js`.
+
+## Group 2 – Naming Conventions
+1. File Naming and Structure:
+   • Frontend:
+     - Page Files: Use lower-case filenames (e.g., index.tsx) as prescribed by Next.js conventions.
+       - **Example**: `pages/index.tsx`, `pages/about.tsx`
+     - Component Files: Use PascalCase for React component files (e.g., WebSiteHeader.tsx, NavBar.tsx).
+       - **Example**: `components/Header.tsx`, `components/Footer.tsx`
+     - Directories: Use clear, descriptive names (e.g., 'pages', 'components', 'WebPageComponents').
+       - **Example**: `src/pages`, `src/components`
+   • Backend:
+     - Use lower-case filenames for modules (e.g., index.js, auth.js, projects.js).
+       - **Example**: `routes/auth.js`, `services/user.js`
+     - When needed, use hyphenation for clarity, but maintain consistency.
+       - **Example**: `helpers/wrap-async.js`
+
+2. Component and Module Naming:
+   • Frontend:
+     - React Components: Define components in PascalCase.
+     - TypeScript Interfaces/Types: Use PascalCase (e.g., WebSiteHeaderProps).
+   • Backend:
+     - Classes (if any) and constructors should be in PascalCase; most helper functions and modules use camelCase.
+
+3. Variable, Function, and Hook Naming:
+   • Use camelCase for variables and function names in both frontend and backend.
+     - **Example**:
+       ```javascript
+       const userName = 'John Doe';
+       function handleLogin() { ... }
+       ```
+   • Custom Hooks: Prefix with 'use' (e.g., useAuth, useForm).
+     - **Example**:
+       ```typescript
+       const useAuth = () => {
+         const [isAuthenticated, setIsAuthenticated] = useState(false);
+         return { isAuthenticated, setIsAuthenticated };
+       };
+       ```
+
+4. Consistency and Readability:
+   • Maintain uniform naming across the project to ensure clarity and ease of maintenance.
+     - **Example**: Use consistent naming conventions for variables, functions, and components, such as camelCase for variables and functions, and PascalCase for components.
+     - **Example**: In `auth.js`, ensure that all function names clearly describe their purpose, such as `handleLogin` or `validateUserInput`.
+
+## Group 3 – Frontend & React Best Practices
+1. Use of Functional Components & TypeScript:
+   • Build all components as functional components.
+     - **Example**:
+       ```typescript
+       const Header: React.FC = () => {
+         return <header>Header Content</header>;
+       };
+       ```
+   • Leverage TypeScript for static type checking and enforce strict prop and state types.
+     - **Example**:
+       ```typescript
+       interface ButtonProps {
+         onClick: () => void;
+       }
+       const Button: React.FC<ButtonProps> = ({ onClick }) => (
+         <button onClick={onClick}>Click me</button>
+       );
+       ```
+
+2. Effective Use of React Hooks:
+   • Utilize useState and useEffect appropriately with proper dependency arrays.
+     - **Example**:
+       ```typescript
+       const [count, setCount] = useState(0);
+       useEffect(() => {
+         console.log('Component mounted');
+       }, []);
+       ```
+   • Create custom hooks to encapsulate shared logic (e.g., useAppSelector).
+     - **Example**:
+       ```typescript
+       const useAuth = () => {
+         const [isAuthenticated, setIsAuthenticated] = useState(false);
+         return { isAuthenticated, setIsAuthenticated };
+       };
+       ```
+
+3. Component Composition & Separation of Concerns:
+   • Separate presentational (stateless) components from container components managing logic.
+     - **Example**: Use `LayoutGuest` to encapsulate common page structures.
+
+4. Code Quality & Readability:
+   • Maintain consistent formatting and adhere to Prettier and ESLint rules.
+   • Use descriptive names for variables, functions, and components.
+   • Document non-trivial logic with inline comments and consider implementing error boundaries where needed.
+   • New code must adhere to these conventions to avoid ambiguity.
+   • Use descriptive names that reflect the purpose and domain, avoiding abbreviations unless standard in the project.
+
+## Group 4 – Backend & API Guidelines
+1. API Endpoint Design & Documentation:
+   • Follow RESTful naming conventions; all route handlers should be named clearly and consistently.
+     - **Example**: Use verbs like `GET`, `POST`, `PUT`, `DELETE` to define actions, e.g., `GET /api/auth/me` to retrieve user info.
+   • Document endpoints with Swagger annotations to provide descriptions, expected request bodies, and response codes.
+     - **Example**:
+       ```javascript
+       /**
+        * @swagger
+        * /api/auth/signin:
+        *   post:
+        *     summary: Sign in a user
+        *     requestBody:
+        *       description: User credentials
+        *       content:
+        *         application/json:
+        *           schema:
+        *             $ref: "#/components/schemas/Auth"
+        *     responses:
+        *       200:
+        *         description: Successful login
+        *       400:
+        *         description: Invalid username/password supplied
+        */
+       ```
+   • Examples (for Auth endpoints):
+       - POST /api/auth/signin/local
+           • Description: Logs the user into the system.
+           • Request Body (application/json):
+               { "email": "admin@flatlogic.com", "password": "password" }
+           • Responses:
+               - 200: Successful login (returns token and user data).
+               - 400: Invalid username/password supplied.
+       - GET /api/auth/me
+           • Description: Retrieves current authorized user information.
+           • Secured via Passport JWT; uses req.currentUser.
+           • Responses:
+               - 200: Returns current user info.
+               - 400: Invalid credentials or missing user data.
+       - POST /api/auth/signup
+           • Description: Registers a new user.
+           • Request Body (application/json):
+               { "email": "admin@flatlogic.com", "password": "password" }
+           • Responses:
+               - 200: New user signed up successfully.
+               - 400: Invalid input supplied.
+               - 500: Server error.
+
+## Group 5 – Testing, Quality Assurance & Error Handling
+1. Testing Guidelines:
+   • Write unit tests for critical backend and frontend components using frameworks such as Jest, React Testing Library, and Mocha/Chai.
+     - **Example**:
+       ```javascript
+       test('should return user data', async () => {
+         const user = await getUserData();
+         expect(user).toHaveProperty('email');
+       });
+       ```
+   • Practice test-driven development and maintain high test coverage.
+   • Regularly update tests following changes in business logic.
+
+2. Quality Assurance:
+   • Enforce code quality with ESLint, Prettier, and static analysis tools.
+   • Integrate continuous testing workflows (CI/CD) to catch issues early.
+     - **Example**: Use GitHub Actions for automated testing and deployment.
+   • Ensure documentation is kept up-to-date with the implemented code.
+
+3. Error Handling:
+   • Back-end:
+       - Wrap asynchronous route handlers with a helper (e.g., wrapAsync) to capture errors.
+         - **Example**:
+           ```javascript
+           router.post('/signin', wrapAsync(async (req, res) => {
+             const user = await AuthService.signin(req.body);
+             res.send(user);
+           }));
+           ```
+       - Use centralized error handling middleware (e.g., commonErrorHandler) for uniform error responses.
+   • Front-end:
+       - Implement error boundaries in React to gracefully handle runtime errors.
+       - Display user-friendly error messages and log errors for further analysis.
+
+2. Authentication & Security:
+   • Protect endpoints by using Passport.js with JWT (e.g., passport.authenticate('jwt', { session: false })).
+     - **Example**:
+       ```javascript
+       router.get('/profile', passport.authenticate('jwt', { session: false }), (req, res) => {
+         res.send(req.user);
+       });
+       ```
+   • Ensure that secure routes check for existence of req.currentUser. If absent, return a ForbiddenError.
+
+3. Consistent Error Handling & Middleware Usage:
+   • Wrap asynchronous route handlers with helpers like wrapAsync for error propagation.
+   • Use centralized error handling middleware (e.g., commonErrorHandler) to capture and format errors uniformly.
+
+4. Modular Code Organization:
+   • Organize backend code into separate files for routes, services, and database access (e.g., auth.js, projects.js, tasks.js).
+   • Use descriptive, lowercase filenames for modules and routes.
+
+5. Endpoint Security Best Practices:
+   • Validate input data and sanitize requests where necessary.
+   • Restrict sensitive operations to authenticated users with proper role-based permissions.
+
+
+────────────────────────────────────────
+Group 6 – Accessibility, UI, and Styling Guidelines (Updated)
+────────────────────────────────────────
+1. Sidebar Styling:
+   • The sidebar is implemented in the authenticated layout via the AsideMenu component, with the actual element defined in AsideMenuLayer (located at frontend/src/components/AsideMenuLayer.tsx) as an <aside> element with id="asideMenu".
+     - **Example**:
+       ```css
+       #asideMenu {
+           background-color: #F8F4E1 !important;
+       }
+       ```
+   • When modifying sidebar styles, target #asideMenu and its child elements rather than generic selectors (e.g., avoid .app-sidebar) to ensure that the changes affect the actual rendered sidebar.
+   • Remove or override any conflicting background utilities (such as an unwanted bg-white) so our desired background color (#F8F4E1) is fully visible. Use a highly specific selector if necessary.
+   • Adjust spacing (padding/margins) at both the container (#asideMenu) and the individual menu item level to maintain a consistent, compact design.
+
+2. General Project Styling and Tailwind CSS Usage:
+   • The application leverages Tailwind CSS extensively, with core styling defined in _theme.css using the @apply directive. Any new modifications should follow this pattern to ensure consistency.
+     - **Example**:
+       ```css
+       .btn {
+           @apply bg-blue-500 text-white;
+       }
+       ```
+   • The themed blocks (like .theme-pink and .theme-green) standardize the UI's appearance. When applying custom overrides, ensure they integrate cleanly into these structures and avoid conflicts or circular dependency errors (e.g., issues when redefining utilities such as text-blue-600).
+   • Adjustments via Tailwind CSS generally require modifying class names in the components and ensuring that global overrides are applied in the correct order. Consistent use of design tokens and custom color codes (e.g., #F8F4E1) throughout the app is crucial to a cohesive design.
+   • Specificity is key. If a change isn't visually reflected as expected, inspect the rendered HTML to identify which classes are taking precedence.

.dockerignore

@@ -0,0 +1,3 @@
+backend/node_modules
+frontend/node_modules
+frontend/build

backend/.eslintignore

@@ -0,0 +1,4 @@
+# Ignore generated and runtime files
+node_modules/
+tmp/
+logs/

backend/.eslintrc.cjs

@@ -0,0 +1,15 @@
+module.exports = {
+  env: {
+    node: true,
+    es2021: true
+  },
+  extends: [
+    'eslint:recommended'
+  ],
+  plugins: [
+    'import'
+  ],
+  rules: {
+    'import/no-unresolved': 'error'
+  }
+};

backend/src/ai/LocalAIApi.js

@@ -0,0 +1,484 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const http = require("http");
+const https = require("https");
+const { URL } = require("url");
+
+let CONFIG_CACHE = null;
+
+class LocalAIApi {
+  static createResponse(params, options) {
+    return createResponse(params, options);
+  }
+
+  static request(pathValue, payload, options) {
+    return request(pathValue, payload, options);
+  }
+
+  static fetchStatus(aiRequestId, options) {
+    return fetchStatus(aiRequestId, options);
+  }
+
+  static awaitResponse(aiRequestId, options) {
+    return awaitResponse(aiRequestId, options);
+  }
+
+  static extractText(response) {
+    return extractText(response);
+  }
+
+  static decodeJsonFromResponse(response) {
+    return decodeJsonFromResponse(response);
+  }
+}
+
+async function createResponse(params, options = {}) {
+  const payload = { ...(params || {}) };
+
+  if (!Array.isArray(payload.input) || payload.input.length === 0) {
+    return {
+      success: false,
+      error: "input_missing",
+      message: 'Parameter "input" is required and must be a non-empty array.',
+    };
+  }
+
+  const cfg = config();
+  if (!payload.model) {
+    payload.model = cfg.defaultModel;
+  }
+
+  const initial = await request(options.path, payload, options);
+  if (!initial.success) {
+    return initial;
+  }
+
+  const data = initial.data;
+  if (data && typeof data === "object" && data.ai_request_id) {
+    const pollTimeout = Number(options.poll_timeout ?? 300);
+    const pollInterval = Number(options.poll_interval ?? 5);
+    return await awaitResponse(data.ai_request_id, {
+      interval: pollInterval,
+      timeout: pollTimeout,
+      headers: options.headers,
+      timeout_per_call: options.timeout,
+      verify_tls: options.verify_tls,
+    });
+  }
+
+  return initial;
+}
+
+async function request(pathValue, payload = {}, options = {}) {
+  const cfg = config();
+  const resolvedPath = pathValue || options.path || cfg.responsesPath;
+
+  if (!resolvedPath) {
+    return {
+      success: false,
+      error: "project_id_missing",
+      message: "PROJECT_ID is not defined; cannot resolve AI proxy endpoint.",
+    };
+  }
+
+  if (!cfg.projectUuid) {
+    return {
+      success: false,
+      error: "project_uuid_missing",
+      message: "PROJECT_UUID is not defined; aborting AI request.",
+    };
+  }
+
+  const bodyPayload = { ...(payload || {}) };
+  if (!bodyPayload.project_uuid) {
+    bodyPayload.project_uuid = cfg.projectUuid;
+  }
+
+  const url = buildUrl(resolvedPath, cfg.baseUrl);
+  const timeout = resolveTimeout(options.timeout, cfg.timeout);
+  const verifyTls = resolveVerifyTls(options.verify_tls, cfg.verifyTls);
+
+  const headers = {
+    Accept: "application/json",
+    "Content-Type": "application/json",
+    [cfg.projectHeader]: cfg.projectUuid,
+  };
+  if (Array.isArray(options.headers)) {
+    for (const header of options.headers) {
+      if (typeof header === "string" && header.includes(":")) {
+        const [name, value] = header.split(":", 2);
+        headers[name.trim()] = value.trim();
+      }
+    }
+  }
+
+  const body = JSON.stringify(bodyPayload);
+  return sendRequest(url, "POST", body, headers, timeout, verifyTls);
+}
+
+async function fetchStatus(aiRequestId, options = {}) {
+  const cfg = config();
+  if (!cfg.projectUuid) {
+    return {
+      success: false,
+      error: "project_uuid_missing",
+      message: "PROJECT_UUID is not defined; aborting status check.",
+    };
+  }
+
+  const statusPath = resolveStatusPath(aiRequestId, cfg);
+  const url = buildUrl(statusPath, cfg.baseUrl);
+  const timeout = resolveTimeout(options.timeout, cfg.timeout);
+  const verifyTls = resolveVerifyTls(options.verify_tls, cfg.verifyTls);
+
+  const headers = {
+    Accept: "application/json",
+    [cfg.projectHeader]: cfg.projectUuid,
+  };
+  if (Array.isArray(options.headers)) {
+    for (const header of options.headers) {
+      if (typeof header === "string" && header.includes(":")) {
+        const [name, value] = header.split(":", 2);
+        headers[name.trim()] = value.trim();
+      }
+    }
+  }
+
+  return sendRequest(url, "GET", null, headers, timeout, verifyTls);
+}
+
+async function awaitResponse(aiRequestId, options = {}) {
+  const timeout = Number(options.timeout ?? 300);
+  const interval = Math.max(Number(options.interval ?? 5), 1);
+  const deadline = Date.now() + Math.max(timeout, interval) * 1000;
+
+  while (true) {
+    const statusResp = await fetchStatus(aiRequestId, {
+      headers: options.headers,
+      timeout: options.timeout_per_call,
+      verify_tls: options.verify_tls,
+    });
+
+    if (statusResp.success) {
+      const data = statusResp.data || {};
+      if (data && typeof data === "object") {
+        if (data.status === "success") {
+          return {
+            success: true,
+            status: 200,
+            data: data.response || data,
+          };
+        }
+        if (data.status === "failed") {
+          return {
+            success: false,
+            status: 500,
+            error: String(data.error || "AI request failed"),
+            data,
+          };
+        }
+      }
+    } else {
+      return statusResp;
+    }
+
+    if (Date.now() >= deadline) {
+      return {
+        success: false,
+        error: "timeout",
+        message: "Timed out waiting for AI response.",
+      };
+    }
+
+    await sleep(interval * 1000);
+  }
+}
+
+function extractText(response) {
+  const payload = response && typeof response === "object" ? response.data || response : null;
+  if (!payload || typeof payload !== "object") {
+    return "";
+  }
+
+  if (Array.isArray(payload.output)) {
+    let combined = "";
+    for (const item of payload.output) {
+      if (!item || !Array.isArray(item.content)) {
+        continue;
+      }
+      for (const block of item.content) {
+        if (
+          block &&
+          typeof block === "object" &&
+          block.type === "output_text" &&
+          typeof block.text === "string" &&
+          block.text.length > 0
+        ) {
+          combined += block.text;
+        }
+      }
+    }
+    if (combined) {
+      return combined;
+    }
+  }
+
+  if (
+    payload.choices &&
+    payload.choices[0] &&
+    payload.choices[0].message &&
+    typeof payload.choices[0].message.content === "string"
+  ) {
+    return payload.choices[0].message.content;
+  }
+
+  return "";
+}
+
+function decodeJsonFromResponse(response) {
+  const text = extractText(response);
+  if (!text) {
+    throw new Error("No text found in AI response.");
+  }
+
+  const parsed = parseJson(text);
+  if (parsed.ok && parsed.value && typeof parsed.value === "object") {
+    return parsed.value;
+  }
+
+  const stripped = stripJsonFence(text);
+  if (stripped !== text) {
+    const parsedStripped = parseJson(stripped);
+    if (parsedStripped.ok && parsedStripped.value && typeof parsedStripped.value === "object") {
+      return parsedStripped.value;
+    }
+    throw new Error(`JSON parse failed after stripping fences: ${parsedStripped.error}`);
+  }
+
+  throw new Error(`JSON parse failed: ${parsed.error}`);
+}
+
+function config() {
+  if (CONFIG_CACHE) {
+    return CONFIG_CACHE;
+  }
+
+  ensureEnvLoaded();
+
+  const baseUrl = process.env.AI_PROXY_BASE_URL || "https://flatlogic.com";
+  const projectId = process.env.PROJECT_ID || null;
+  let responsesPath = process.env.AI_RESPONSES_PATH || null;
+  if (!responsesPath && projectId) {
+    responsesPath = `/projects/${projectId}/ai-request`;
+  }
+
+  const timeout = resolveTimeout(process.env.AI_TIMEOUT, 30);
+  const verifyTls = resolveVerifyTls(process.env.AI_VERIFY_TLS, true);
+
+  CONFIG_CACHE = {
+    baseUrl,
+    responsesPath,
+    projectId,
+    projectUuid: process.env.PROJECT_UUID || null,
+    projectHeader: process.env.AI_PROJECT_HEADER || "project-uuid",
+    defaultModel: process.env.AI_DEFAULT_MODEL || "gpt-5-mini",
+    timeout,
+    verifyTls,
+  };
+
+  return CONFIG_CACHE;
+}
+
+function buildUrl(pathValue, baseUrl) {
+  const trimmed = String(pathValue || "").trim();
+  if (trimmed === "") {
+    return baseUrl;
+  }
+  if (trimmed.startsWith("http://") || trimmed.startsWith("https://")) {
+    return trimmed;
+  }
+  if (trimmed.startsWith("/")) {
+    return `${baseUrl}${trimmed}`;
+  }
+  return `${baseUrl}/${trimmed}`;
+}
+
+function resolveStatusPath(aiRequestId, cfg) {
+  const basePath = (cfg.responsesPath || "").replace(/\/+$/, "");
+  if (!basePath) {
+    return `/ai-request/${encodeURIComponent(String(aiRequestId))}/status`;
+  }
+  const normalized = basePath.endsWith("/ai-request") ? basePath : `${basePath}/ai-request`;
+  return `${normalized}/${encodeURIComponent(String(aiRequestId))}/status`;
+}
+
+function sendRequest(urlString, method, body, headers, timeoutSeconds, verifyTls) {
+  return new Promise((resolve) => {
+    let targetUrl;
+    try {
+      targetUrl = new URL(urlString);
+    } catch (err) {
+      resolve({
+        success: false,
+        error: "invalid_url",
+        message: err.message,
+      });
+      return;
+    }
+
+    const isHttps = targetUrl.protocol === "https:";
+    const requestFn = isHttps ? https.request : http.request;
+    const options = {
+      protocol: targetUrl.protocol,
+      hostname: targetUrl.hostname,
+      port: targetUrl.port || (isHttps ? 443 : 80),
+      path: `${targetUrl.pathname}${targetUrl.search}`,
+      method: method.toUpperCase(),
+      headers,
+      timeout: Math.max(Number(timeoutSeconds || 30), 1) * 1000,
+    };
+    if (isHttps) {
+      options.rejectUnauthorized = Boolean(verifyTls);
+    }
+
+    const req = requestFn(options, (res) => {
+      let responseBody = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => {
+        responseBody += chunk;
+      });
+      res.on("end", () => {
+        const status = res.statusCode || 0;
+        const parsed = parseJson(responseBody);
+        const payload = parsed.ok ? parsed.value : responseBody;
+
+        if (status >= 200 && status < 300) {
+          const result = {
+            success: true,
+            status,
+            data: payload,
+          };
+          if (!parsed.ok) {
+            result.json_error = parsed.error;
+          }
+          resolve(result);
+          return;
+        }
+
+        const errorMessage =
+          parsed.ok && payload && typeof payload === "object"
+            ? String(payload.error || payload.message || "AI proxy request failed")
+            : String(responseBody || "AI proxy request failed");
+
+        resolve({
+          success: false,
+          status,
+          error: errorMessage,
+          response: payload,
+          json_error: parsed.ok ? undefined : parsed.error,
+        });
+      });
+    });
+
+    req.on("timeout", () => {
+      req.destroy(new Error("request_timeout"));
+    });
+
+    req.on("error", (err) => {
+      resolve({
+        success: false,
+        error: "request_failed",
+        message: err.message,
+      });
+    });
+
+    if (body) {
+      req.write(body);
+    }
+    req.end();
+  });
+}
+
+function parseJson(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    return { ok: false, error: "empty_response" };
+  }
+  try {
+    return { ok: true, value: JSON.parse(value) };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+function stripJsonFence(text) {
+  const trimmed = text.trim();
+  if (trimmed.startsWith("```json")) {
+    return trimmed.replace(/^```json/, "").replace(/```$/, "").trim();
+  }
+  if (trimmed.startsWith("```")) {
+    return trimmed.replace(/^```/, "").replace(/```$/, "").trim();
+  }
+  return text;
+}
+
+function resolveTimeout(value, fallback) {
+  const parsed = Number.parseInt(String(value ?? fallback), 10);
+  return Number.isNaN(parsed) ? Number(fallback) : parsed;
+}
+
+function resolveVerifyTls(value, fallback) {
+  if (value === undefined || value === null) {
+    return Boolean(fallback);
+  }
+  return String(value).toLowerCase() !== "false" && String(value) !== "0";
+}
+
+function ensureEnvLoaded() {
+  if (process.env.PROJECT_UUID && process.env.PROJECT_ID) {
+    return;
+  }
+
+  const envPath = path.resolve(__dirname, "../../../../.env");
+  if (!fs.existsSync(envPath)) {
+    return;
+  }
+
+  let content;
+  try {
+    content = fs.readFileSync(envPath, "utf8");
+  } catch (err) {
+    throw new Error(`Failed to read executor .env: ${err.message}`);
+  }
+
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#") || !trimmed.includes("=")) {
+      continue;
+    }
+    const [rawKey, ...rest] = trimmed.split("=");
+    const key = rawKey.trim();
+    if (!key) {
+      continue;
+    }
+    const value = rest.join("=").trim().replace(/^['"]|['"]$/g, "");
+    if (!process.env[key]) {
+      process.env[key] = value;
+    }
+  }
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = {
+  LocalAIApi,
+  createResponse,
+  request,
+  fetchStatus,
+  awaitResponse,
+  extractText,
+  decodeJsonFromResponse,
+};

backend/src/db/migrations/1754861625213.js

@@ -0,0 +1,65 @@
+module.exports = {
+    /**
+     * @param {QueryInterface} queryInterface
+     * @param {Sequelize} Sequelize
+     * @returns {Promise<void>}
+     */
+    async up(queryInterface, Sequelize) {
+        /**
+         * @type {Transaction}
+         */
+        const transaction = await queryInterface.sequelize.transaction();
+        try {
+            
+                
+                    
+                    await queryInterface.addColumn(
+                      'listings',
+                      'listing_type',
+                      {
+                          type: Sequelize.DataTypes.ENUM,
+                          
+                          
+                            values: ['value'],
+                          
+                          
+                      },
+                      { transaction }
+                    );
+                
+            
+            
+            
+            await transaction.commit();
+        } catch (err) {
+            await transaction.rollback();
+            throw err;
+        }
+    },
+    /**
+     * @param {QueryInterface} queryInterface
+     * @param {Sequelize} Sequelize
+     * @returns {Promise<void>}
+     */
+    async down(queryInterface, Sequelize) {
+        /**
+         * @type {Transaction}
+         */
+        const transaction = await queryInterface.sequelize.transaction();
+        try {
+            
+                
+                    await queryInterface.removeColumn(
+                        'listings',
+                        'listing_type',
+                        { transaction }
+                    );
+                
+            
+            await transaction.commit();
+        } catch (err) {
+            await transaction.rollback();
+            throw err;
+        }
+    }
+};

backend/src/db/migrations/20260316000000-create-files.js

@@ -0,0 +1,124 @@
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      const rows = await queryInterface.sequelize.query(
+        "SELECT to_regclass('public.files') AS regclass_name;",
+        {
+          transaction,
+          type: Sequelize.QueryTypes.SELECT,
+        },
+      );
+      const tableName = rows[0].regclass_name;
+
+      if (tableName) {
+        await transaction.commit();
+        return;
+      }
+
+      await queryInterface.createTable(
+        'files',
+        {
+          id: {
+            type: Sequelize.DataTypes.UUID,
+            defaultValue: Sequelize.DataTypes.UUIDV4,
+            primaryKey: true,
+          },
+          belongsTo: {
+            type: Sequelize.DataTypes.STRING(255),
+            allowNull: true,
+          },
+          belongsToId: {
+            type: Sequelize.DataTypes.UUID,
+            allowNull: true,
+          },
+          belongsToColumn: {
+            type: Sequelize.DataTypes.STRING(255),
+            allowNull: true,
+          },
+          name: {
+            type: Sequelize.DataTypes.STRING(2083),
+            allowNull: false,
+          },
+          sizeInBytes: {
+            type: Sequelize.DataTypes.INTEGER,
+            allowNull: true,
+          },
+          privateUrl: {
+            type: Sequelize.DataTypes.STRING(2083),
+            allowNull: true,
+          },
+          publicUrl: {
+            type: Sequelize.DataTypes.STRING(2083),
+            allowNull: false,
+          },
+          createdAt: {
+            type: Sequelize.DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: Sequelize.DataTypes.DATE,
+            allowNull: false,
+          },
+          deletedAt: {
+            type: Sequelize.DataTypes.DATE,
+            allowNull: true,
+          },
+          createdById: {
+            type: Sequelize.DataTypes.UUID,
+            allowNull: true,
+            references: {
+              key: 'id',
+              model: 'users',
+            },
+            onDelete: 'SET NULL',
+            onUpdate: 'CASCADE',
+          },
+          updatedById: {
+            type: Sequelize.DataTypes.UUID,
+            allowNull: true,
+            references: {
+              key: 'id',
+              model: 'users',
+            },
+            onDelete: 'SET NULL',
+            onUpdate: 'CASCADE',
+          },
+        },
+        { transaction },
+      );
+
+      await transaction.commit();
+    } catch (err) {
+      await transaction.rollback();
+      throw err;
+    }
+  },
+
+  async down(queryInterface, Sequelize) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      const rows = await queryInterface.sequelize.query(
+        "SELECT to_regclass('public.files') AS regclass_name;",
+        {
+          transaction,
+          type: Sequelize.QueryTypes.SELECT,
+        },
+      );
+      const tableName = rows[0].regclass_name;
+
+      if (!tableName) {
+        await transaction.commit();
+        return;
+      }
+
+      await queryInterface.dropTable('files', { transaction });
+      await transaction.commit();
+    } catch (err) {
+      await transaction.rollback();
+      throw err;
+    }
+  },
+};

backend/src/db/migrations/20260316001000-create-users-custom-permissions-join-table.js

@@ -0,0 +1,77 @@
+module.exports = {
+  async up(queryInterface, Sequelize) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      const rows = await queryInterface.sequelize.query(
+        "SELECT to_regclass('public.\"usersCustom_permissionsPermissions\"') AS regclass_name;",
+        {
+          transaction,
+          type: Sequelize.QueryTypes.SELECT,
+        },
+      );
+      const tableName = rows[0].regclass_name;
+
+      if (tableName) {
+        await transaction.commit();
+        return;
+      }
+
+      await queryInterface.createTable(
+        'usersCustom_permissionsPermissions',
+        {
+          createdAt: {
+            type: Sequelize.DataTypes.DATE,
+            allowNull: false,
+          },
+          updatedAt: {
+            type: Sequelize.DataTypes.DATE,
+            allowNull: false,
+          },
+          users_custom_permissionsId: {
+            type: Sequelize.DataTypes.UUID,
+            allowNull: false,
+            primaryKey: true,
+          },
+          permissionId: {
+            type: Sequelize.DataTypes.UUID,
+            allowNull: false,
+            primaryKey: true,
+          },
+        },
+        { transaction },
+      );
+
+      await transaction.commit();
+    } catch (err) {
+      await transaction.rollback();
+      throw err;
+    }
+  },
+
+  async down(queryInterface, Sequelize) {
+    const transaction = await queryInterface.sequelize.transaction();
+
+    try {
+      const rows = await queryInterface.sequelize.query(
+        "SELECT to_regclass('public.\"usersCustom_permissionsPermissions\"') AS regclass_name;",
+        {
+          transaction,
+          type: Sequelize.QueryTypes.SELECT,
+        },
+      );
+      const tableName = rows[0].regclass_name;
+
+      if (!tableName) {
+        await transaction.commit();
+        return;
+      }
+
+      await queryInterface.dropTable('usersCustom_permissionsPermissions', { transaction });
+      await transaction.commit();
+    } catch (err) {
+      await transaction.rollback();
+      throw err;
+    }
+  },
+};

backend/src/routes/sql.js

@@ -0,0 +1,61 @@
+const express = require('express');
+const db = require('../db/models');
+const wrapAsync = require('../helpers').wrapAsync;
+
+const router = express.Router();
+
+/**
+ * @swagger
+ * /api/sql:
+ *  post:
+ *    security:
+ *      - bearerAuth: []
+ *    summary: Execute a SELECT-only SQL query
+ *    description: Executes a read-only SQL query and returns rows.
+ *    requestBody:
+ *      required: true
+ *      content:
+ *        application/json:
+ *          schema:
+ *            type: object
+ *            properties:
+ *              sql:
+ *                type: string
+ *            required:
+ *              - sql
+ *    responses:
+ *      200:
+ *        description: Query result
+ *      400:
+ *        description: Invalid SQL
+ *      401:
+ *        $ref: "#/components/responses/UnauthorizedError"
+ *      500:
+ *        description: Internal server error
+ */
+router.post(
+  '/',
+  wrapAsync(async (req, res) => {
+    const { sql } = req.body;
+    if (typeof sql !== 'string' || !sql.trim()) {
+      return res.status(400).json({ error: 'SQL is required' });
+    }
+
+    const normalized = sql.trim().replace(/;+\s*$/, '');
+    if (!/^select\b/i.test(normalized)) {
+      return res.status(400).json({ error: 'Only SELECT statements are allowed' });
+    }
+
+    if (normalized.includes(';')) {
+      return res.status(400).json({ error: 'Only a single SELECT statement is allowed' });
+    }
+
+    const rows = await db.sequelize.query(normalized, {
+      type: db.Sequelize.QueryTypes.SELECT,
+    });
+
+    return res.status(200).json({ rows });
+  }),
+);
+
+module.exports = router;

frontend/.eslintignore

@@ -0,0 +1,3 @@
+# Ignore generated files
+build/*
+next-env.d.ts

frontend/src/pages/search-wizard/index.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import Head from 'next/head';
+import LayoutGuest from '../../layouts/Guest';
+import WebSiteHeader from '../../components/WebPageComponents/Header';
+import WebSiteFooter from '../../components/WebPageComponents/Footer';
+import Link from 'next/link';
+
+export default function SearchWizardPage() {
+ return (
+   <LayoutGuest>
+     <Head>
+       <title>Start Your Search | RentWhiz</title>
+     </Head>
+     <WebSiteHeader />
+     <main className="flex-grow container mx-auto py-10 text-center">
+       <h1 className="text-4xl font-bold mb-8">Start Your Search</h1>
+       <div className="flex justify-center space-x-4">
+         <Link href="/search-wizard/place" className="px-8 py-4 bg-blue-600 text-white rounded-lg hover:bg-blue-700">
+           I&apos;m Looking for a Place
+         </Link>
+         <Link href="/search-wizard/roommate" className="px-8 py-4 bg-green-600 text-white rounded-lg hover:bg-green-700">
+           I&apos;m Looking for a Roommate
+         </Link>
+       </div>
+     </main>
+     <WebSiteFooter />
+   </LayoutGuest>
+ );
+}

frontend/src/pages/search-wizard/place.tsx

@@ -0,0 +1,43 @@
+import React, { useEffect } from 'react';
+import type { ReactElement } from 'react';
+import Head from 'next/head';
+import LayoutGuest from '../../../layouts/Guest';
+import WebSiteHeader from '../../../components/WebPageComponents/Header';
+import WebSiteFooter from '../../../components/WebPageComponents/Footer';
+import { useAppDispatch, useAppSelector } from '../../../stores/hooks';
+import { getAmenities } from '../../../stores/amenities/amenitiesSlice';
+// Import other required slices for house rules/hobbies here if needed
+
+export default function SearchWizardPlacePage() {
+  const dispatch = useAppDispatch();
+  const { amenities } = useAppSelector((state) => state.amenities);
+
+  useEffect(() => {
+    dispatch(getAmenities());
+    // Dispatch other necessary actions here
+  }, [dispatch]);
+
+  return (
+    <LayoutGuest>
+      <Head>
+        <title>Find a Place | RentWhiz</title>
+      </Head>
+      <WebSiteHeader />
+      <main className="flex-grow container mx-auto py-10">
+        <h1 className="text-3xl font-bold mb-6">Property & Roommate Preferences</h1>
+        {/* Render form fields here */}
+        <div className="p-6 bg-white rounded-lg shadow">
+          <h2 className="text-xl mb-4">Property Preferences</h2>
+          {/* Add form inputs */}
+          <h2 className="text-xl mt-6 mb-4">Roommate Preferences</h2>
+          {/* Add form inputs */}
+        </div>
+      </main>
+      <WebSiteFooter />
+    </LayoutGuest>
+  );
+}
+
+SearchWizardPlacePage.getLayout = function getLayout(page: ReactElement) {
+  return <LayoutGuest>{page}</LayoutGuest>;
+};