Project Settings Documentation

Contents

• Purpose
• When the settings page appears
• Database structure
• API routes
• Component architecture
• Usage in the application
• Future expansion

Purpose

Project settings represent the configuration layer for each project in AISTEAM. These settings control how agents interact with the project, which domains are associated with it, hosting configuration and feature flags that enable or disable specific behaviors.

The following panels and systems rely on project settings:

• Assistant System uses agent_defaults to determine which agent should handle conversations and which task types are allowed
• Performance Panel may use domain settings to configure monitoring endpoints
• Web Design Panel uses domain configuration to identify staging and production environments
• Hosting Panel displays hosting provider and region information from settings
• Feature Flags control experimental features or project specific behaviors

When the settings page appears

The Project Settings interface can be accessed through two different paths, both using the same underlying component for consistency.

From project listings modal

When viewing the project listings page, each project card or row includes a Settings button. Clicking this button opens a modal overlay that displays the full Project Settings interface. The modal uses the same ProjectSettingsContainer component as the full page, ensuring identical behavior and validation.

User clicks Settings button on project card
  → ProjectSettingsModal opens
    → ProjectSettingsContainer renders inside modal
      → Settings are loaded and displayed

From project details full page

The project details page header includes a Settings link that navigates to a dedicated full page view. This route is located at /projects/[projectId]/settings and provides the same settings interface without the modal overlay. This path is useful when users need to reference other parts of the application while configuring settings.

User clicks Settings link in project header
  → Navigation to /projects/[projectId]/settings
    → ProjectSettingsPage renders
      → ProjectSettingsContainer renders on full page
        → Settings are loaded and displayed

Database structure

Project settings are stored in a dedicated table that maintains a one to one relationship with projects. The settings are stored as a JSONB object, allowing flexible schema evolution without migrations.

project_settings table

Stores all project configuration in a structured JSONB format.

CREATE TABLE IF NOT EXISTS project_settings (
  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  project_id uuid NOT NULL UNIQUE REFERENCES projects(id) ON DELETE CASCADE,
  settings jsonb NOT NULL DEFAULT '{}',
  created_at timestamptz NOT NULL DEFAULT now(),
  updated_at timestamptz NOT NULL DEFAULT now()
);

CREATE INDEX IF NOT EXISTS idx_project_settings_project_id 
  ON project_settings(project_id);

Settings JSONB structure

The settings column contains a JSON object with the following top level categories:

{
  "general": {
    "name": "string",
    "description": "string",
    "client": "string",
    "status": "active" | "staging" | "development" | "archived"
  },
  "domains": {
    "primary": "string",
    "staging": "string",
    "development": ["string"]
  },
  "hosting": {
    "provider": "string",
    "region": "string",
    "ssl_enabled": boolean
  },
  "agent_defaults": {
    "default_agent": "chief" | "deliveryLead" | "clientSuccess" | "creativeLead" | "growthLead" | "technicalLead" | "webEngineer",
    "allowed_task_types": ["create_page", "update_content", "create_post", "create_product", "create_ticket", "run_audit", "update_settings"],
    "auto_execute": boolean
  },
  "feature_flags": {
    "[key]": boolean | string | number | null
  }
}

API routes

GET /api/projects/settings

Retrieves project settings. If no settings exist, creates a default entry and returns it.

Query parameters:

• projectId (required) - UUID of the project

Response shape:

{
  "settings": {
    "general": { ... },
    "domains": { ... },
    "hosting": { ... },
    "agent_defaults": { ... },
    "feature_flags": { ... }
  }
}

If the project has no settings record, the API automatically creates one with default values before returning.

PATCH /api/projects/settings

Updates project settings by merging the provided updates into the existing settings object.

Request body:

{
  "projectId": "uuid",
  "updates": {
    "general": { "status": "active" },
    "domains": { "primary": "example.com" },
    "hosting": { "provider": "Vercel" },
    "agent_defaults": { "default_agent": "webEngineer" },
    "feature_flags": { "new_feature": true }
  }
}

Response shape:

{
  "ok": true,
  "settings": {
    "general": { ... },
    "domains": { ... },
    "hosting": { ... },
    "agent_defaults": { ... },
    "feature_flags": { ... }
  }
}

The PATCH endpoint performs a deep merge, meaning you can update individual fields within categories without affecting other fields. The API uses upsert logic, so it will create a record if one does not exist.

Component architecture

The Project Settings feature uses a reusable container component that is rendered in both modal and full page contexts. This ensures consistent behavior and validation across both access paths.

page.tsx

Located at app/projects/[projectId]/settings/page.tsx, this is the full page route component. It extracts the projectId from URL parameters and renders ProjectSettingsContainer without any modal wrapper.

ProjectSettingsContainer

The main container component that manages all settings state and API interactions. Located at app/projects/[projectId]/settings/ProjectSettingsContainer.tsx.

Responsibilities:

• Fetches settings from the API on mount
• Manages local state for all settings categories
• Handles save operations by calling the PATCH endpoint
• Renders all category components in a form layout
• Displays loading and error states
• Accepts an optional onClose callback for modal usage

Category components

Each settings category has its own component that handles editing and validation for that specific section:

• GeneralInfoSettings - Project name, description, client, status
• DomainSettings - Primary domain, staging domain, development domains array
• HostingSettings - Hosting provider, region, SSL enabled toggle
• AgentDefaultsSettings - Default agent selection, allowed task types checkboxes, auto execute toggle
• FeatureFlagsSettings - Dynamic feature flags with support for boolean, string, number and null values

Each category component receives the current settings for its category and an onUpdate callback. When a user makes changes, the component calls onUpdate with the partial updates, which the container merges into its state.

Modal wrapper

Located at app/components/projects/ProjectSettingsModal.tsx, this component provides the modal overlay and close functionality. It renders ProjectSettingsContainer inside a centered modal with backdrop, matching the styling pattern used by the trend settings modal.

The modal passes the onClose callback to ProjectSettingsContainer, which triggers it after a successful save operation.

Usage in the application

Requesting settings from panels

Other panels and components can fetch project settings by calling the GET endpoint:

const response = await fetch(`/api/projects/settings?projectId=${projectId}`);
const data = await response.json();
const settings = data.settings;

// Access specific categories
const primaryDomain = settings.domains?.primary;
const defaultAgent = settings.agent_defaults?.default_agent;
const sslEnabled = settings.hosting?.ssl_enabled;

Agent defaults consumption

The assistant system uses agent_defaults to configure behavior for each project:

• default_agent - When a conversation starts without an explicit agent selection, this value determines which agent handles the initial request
• allowed_task_types - The execution API checks this array before allowing task execution. Tasks with types not in this list are rejected
• auto_execute - When true, agents can execute tasks without explicit user confirmation, respecting the law of no return for irreversible actions

The assistant chat API loads these settings when projectContext is provided and injects them into agent prompts.

Feature flags consumption

Feature flags allow enabling or disabling features on a per project basis. Components can check feature flags like this:

const settings = await fetchSettings(projectId);
const enableNewFeature = settings.feature_flags?.new_feature === true;

if (enableNewFeature) {
  // Render or enable the new feature
}

Feature flags support boolean, string, number and null values, making them flexible for various use cases beyond simple on off toggles.

Future expansion

The project_settings table uses JSONB for the settings column, which provides significant flexibility for future expansion without requiring database migrations.

New settings categories can be added by:

• Adding new top level keys to the settings JSONB object
• Creating new category components that handle the new settings
• Updating the TypeScript types in types.ts
• Updating the DEFAULT_SETTINGS constant in the API route

The existing API routes will automatically handle new categories because they perform deep merges and preserve unknown keys. This means you can add new settings without breaking existing functionality or requiring immediate updates to all consumers.

Potential future categories might include:

• Integration settings for third party services
• Notification preferences
• Custom branding configuration
• Performance monitoring thresholds
• Backup and retention policies

Related pages

• Project Listings
• Project Details
• Agents