tractatus/docs/USER_GUIDE_PROJECTS.md

# Multi-Project Governance - User Guide

**Version:** 1.0
**Last Updated:** January 15, 2025

---

## Table of Contents

1. [Introduction](#introduction)
2. [Getting Started](#getting-started)
3. [Managing Projects](#managing-projects)
4. [Managing Variables](#managing-variables)
5. [Viewing Rules with Variable Substitution](#viewing-rules-with-variable-substitution)
6. [Common Workflows](#common-workflows)
7. [Best Practices](#best-practices)
8. [Troubleshooting](#troubleshooting)
9. [FAQ](#faq)

---

## Introduction

### What is Multi-Project Governance?

The Multi-Project Governance system allows you to manage governance rules across multiple codebases or applications. Each project can have its own configuration variables, and governance rules can be rendered with project-specific values.

### Key Features

✅ **Project Management** - Create and manage multiple projects with their own configurations
✅ **Variable Substitution** - Define variables that are automatically replaced in governance rules
✅ **Context-Aware Rules** - View rules with project-specific values substituted
✅ **Centralized Configuration** - Manage all project variables in one place
✅ **Audit Trail** - Track all changes to projects and variables

### Use Cases

- **Multi-tenant systems**: Different configurations for different customers
- **Environment management**: Separate configs for dev, staging, production
- **Microservices**: Shared governance rules with service-specific variables
- **Multi-codebase organizations**: Consistent rules across different projects

---

## Getting Started

### Prerequisites

- Admin access to the Tractatus system
- Valid authentication token
- Basic understanding of your project's configuration needs

### Accessing the Project Manager

1. Log in to the admin dashboard at `/admin/login.html`
2. Navigate to **Projects** in the top navigation bar
3. You'll see the Project Manager dashboard

### Dashboard Overview

The Project Manager dashboard shows:
- **Total Projects**: All projects in the system
- **Active Projects**: Currently active projects
- **Variables**: Total number of variable values across all projects
- **DB Types**: Number of unique database types in use

---

## Managing Projects

### Creating a New Project

**Step 1: Click "New Project" Button**
- Located in the top-right corner of the Project Manager page

**Step 2: Fill Out Project Information**

**Required Fields:**
- **Project ID**: Unique identifier (e.g., `my-application`)
  - Use kebab-case (lowercase with hyphens)
  - Cannot be changed after creation
  - Examples: `tractatus`, `family-history`, `sydigital`

- **Project Name**: Display name (e.g., "My Application")
  - Used in UI displays
  - Can be updated later

**Optional Fields:**
- **Description**: Brief description of the project
- **Repository URL**: Link to Git repository
- **Tech Stack**:
  - Framework (e.g., Express.js, Next.js)
  - Database (e.g., MongoDB, PostgreSQL)
  - Frontend (e.g., React, Vanilla JavaScript)
  - CSS Framework (e.g., Tailwind CSS)
- **Metadata**: Custom JSON data for additional project information
- **Active Status**: Whether the project is currently active (checkbox)

**Step 3: Save Project**
- Click "Create Project"
- You'll see a success notification
- The project will appear in the projects grid

### Viewing Project Details

1. Find the project in the projects grid
2. Click the **"View Details"** button
3. A modal will open showing:
   - All project information
   - Tech stack badges
   - Repository link (if provided)
   - List of all variables with their values
   - Metadata in a formatted view

### Editing a Project

1. Click the **"Edit"** button on a project card
2. Modify any fields (except Project ID)
3. Click "Update Project" to save changes

**Common Edits:**
- Update project description
- Change repository URL
- Update tech stack information
- Add/modify metadata
- Activate/deactivate project

### Deleting a Project

**⚠️ Important: Deletion affects all associated variables**

1. Click the **"Delete"** button on a project card
2. Review the confirmation dialog:
   - Shows what will be deleted/deactivated
   - Explains soft delete vs hard delete
3. Confirm deletion

**Soft Delete (Default):**
- Sets project `active: false`
- Deactivates all associated variables
- Data remains in database (can be reactivated)

**Hard Delete (via API):**
- Permanently removes project and all variables
- Cannot be undone
- Use `DELETE /api/admin/projects/:id?hard=true`

### Filtering and Sorting Projects

**Status Filter:**
- All - Show all projects
- Active Only - Show only active projects (default)
- Inactive Only - Show only inactive projects

**Database Filter:**
- Filter by database type (MongoDB, PostgreSQL, MySQL)

**Sort Options:**
- Name (A-Z)
- Project ID
- Variable Count (most to least)
- Last Updated (newest first)

**Clear Filters:**
- Click "Clear Filters" button to reset all filters

---

## Managing Variables

### What are Variables?

Variables are placeholders in governance rules that get replaced with project-specific values.

**Example:**
- Template rule: `"Connect to database ${DB_NAME} on port ${DB_PORT}"`
- For `tractatus` project: `"Connect to database tractatus_prod on port 27017"`
- For `family-history` project: `"Connect to database family_history_dev on port 27017"`

### Variable Naming Rules

✅ **Valid Variable Names:**
- Must be UPPER_SNAKE_CASE
- Start with uppercase letter (A-Z)
- Can contain uppercase letters, numbers, and underscores
- Examples: `DB_NAME`, `API_KEY`, `MAX_CONNECTIONS`, `FEATURE_FLAG_2`

❌ **Invalid Variable Names:**
- `dbName` (camelCase)
- `db_name` (lowercase)
- `DB-NAME` (hyphens)
- `2_DB_NAME` (starts with number)

### Adding Variables to a Project

**Method 1: From Project Manager**

1. Find the project in the projects grid
2. Click **"Variables (X)"** button
3. In the Variables modal, click **"Add Variable"**
4. Fill out the form:
   - **Variable Name**: UPPER_SNAKE_CASE (e.g., `DB_NAME`)
   - **Value**: The actual value (e.g., `tractatus_prod`)
   - **Description**: What this variable represents (optional but recommended)
   - **Category**: Choose from dropdown (database, config, url, etc.)
   - **Data Type**: string, number, boolean, or json
5. Click "Add Variable"

**Method 2: From Project Editor**

1. Click "Edit" on a project
2. Switch to the "Variables" tab
3. Follow the same process as Method 1

### Variable Categories

Organize variables by category for better management:

- **database** - Database configuration (DB_NAME, DB_PORT, DB_USER)
- **config** - Application configuration (APP_PORT, LOG_LEVEL, TIMEOUT)
- **url** - URLs and endpoints (API_BASE_URL, WEBHOOK_URL)
- **path** - File paths and directories (UPLOAD_DIR, LOG_PATH)
- **security** - Security credentials (API_KEY, SECRET_KEY) ⚠️ Handle with care
- **feature_flag** - Feature toggles (ENABLE_ANALYTICS, BETA_FEATURES)
- **other** - Miscellaneous variables

### Variable Data Types

Choose the appropriate data type for each variable:

- **string** (default) - Text values (`"tractatus_prod"`, `"https://api.example.com"`)
- **number** - Numeric values (`27017`, `3000`, `1.5`)
- **boolean** - True/false flags (`true`, `false`)
- **json** - Complex JSON objects (`{"key": "value"}`)

### Editing Variables

1. Open the Variables modal for a project
2. Find the variable you want to edit
3. Click the **edit (✏️)** icon
4. Modify the fields (all except variable name can be changed)
5. Click "Update Variable"

**Note:** To rename a variable, delete the old one and create a new one.

### Deleting Variables

1. Open the Variables modal for a project
2. Find the variable you want to delete
3. Click the **delete (🗑️)** icon
4. Confirm deletion

**⚠️ Warning:** Deleting a variable will leave `${VAR_NAME}` placeholders in rules unreplaced.

### Batch Operations (via API)

For bulk variable management, use the batch API endpoint:

```javascript
POST /api/admin/projects/:projectId/variables/batch
{
  "variables": [
    { "variableName": "DB_NAME", "value": "my_db", "category": "database" },
    { "variableName": "DB_PORT", "value": "5432", "category": "database", "dataType": "number" }
  ]
}
```

See [API Documentation](./api/PROJECTS_API.md) for details.

---

## Viewing Rules with Variable Substitution

### Using the Project Selector

The Rule Manager now includes a **Project Selector** that allows you to view rules with project-specific variable values substituted.

**Step 1: Navigate to Rule Manager**
- Go to `/admin/rule-manager.html`
- You'll see the project selector at the top of the page

**Step 2: Select a Project**
- Choose a project from the dropdown
- Or select "All Projects (Template View)" to see template rules

**Step 3: View Rendered Rules**

When a project is selected, each rule card shows:

**Template Text** (gray box):
- Original rule with `${VARIABLE}` placeholders
- Shows the template that applies to all projects

**Rendered Text** (indigo box):
- Rule with actual values substituted
- Shows "Rendered (Project Name)" header
- This is what the rule means for the selected project

**Example Display:**

```
┌─────────────────────────────────────────────┐
│ UNIVERSAL | OPERATIONAL | HIGH              │
│                                    inst_001 │
├─────────────────────────────────────────────┤
│ 🏷️ TEMPLATE                                 │
│ Connect to database ${DB_NAME} on port    │
│ ${DB_PORT} using credentials ${DB_USER}    │
├─────────────────────────────────────────────┤
│ ✅ RENDERED (Tractatus AI Safety Framework) │
│ Connect to database tractatus_prod on port │
│ 27017 using credentials admin              │
└─────────────────────────────────────────────┘
```

### Understanding Variable Substitution

**What Happens:**
1. System detects all `${VARIABLE_NAME}` placeholders in rule text
2. Looks up each variable for the selected project
3. Replaces placeholders with actual values
4. Shows both template and rendered versions

**Missing Variables:**
- If a variable is not defined for a project, it remains as `${VAR_NAME}` in rendered text
- Example: `"Using API key ${API_KEY}"` → `"Using API key ${API_KEY}"` (if API_KEY not defined)

**Variable Detection:**
- Only UPPER_SNAKE_CASE variables are recognized
- Pattern: `${[A-Z][A-Z0-9_]*}`
- Case-sensitive: `${db_name}` will NOT be substituted

---

## Common Workflows

### Workflow 1: Setting Up a New Project

**Scenario:** You're adding a new application to your governance system.

1. **Create the project**
   - Click "New Project"
   - Enter Project ID: `my-new-app`
   - Enter Name: "My New Application"
   - Add description and tech stack
   - Click "Create Project"

2. **Add essential variables**
   - Click "Variables (0)" on the new project
   - Add core variables:
     ```
     DB_NAME = "my_new_app_db"
     DB_PORT = "5432"
     APP_PORT = "3000"
     LOG_LEVEL = "info"
     ```

3. **Review rules with your context**
   - Go to Rule Manager
   - Select "My New Application" from project selector
   - Review how universal rules apply to your project
   - Check for any missing variables (shown as `${VAR_NAME}`)

4. **Add missing variables**
   - Note any `${MISSING_VAR}` placeholders
   - Return to Project Manager
   - Add the missing variables

### Workflow 2: Updating Configuration for Deployment

**Scenario:** Moving a project from development to production.

1. **Create production project**
   - Duplicate the dev project settings
   - Change ID to `app-production`
   - Update description

2. **Update variables for production**
   - Change `DB_NAME` from `app_dev` to `app_prod`
   - Update `LOG_LEVEL` from `debug` to `warn`
   - Change `API_BASE_URL` to production endpoint
   - Update any environment-specific variables

3. **Verify production rules**
   - Select production project in Rule Manager
   - Review rendered rules to ensure they match production requirements
   - Check that all sensitive variables are set correctly

### Workflow 3: Managing Multi-Tenant Configuration

**Scenario:** You have different customers using the same codebase.

1. **Create project per customer**
   ```
   customer-acme
   customer-globex
   customer-initech
   ```

2. **Set customer-specific variables**
   ```
   CUSTOMER_NAME = "Acme Corp"
   CUSTOMER_ID = "acme-001"
   CUSTOMER_DB = "acme_tenant_db"
   FEATURE_ANALYTICS = "true"
   ```

3. **Use template rules**
   - Create universal rules with customer variables
   - Example: `"Store customer ${CUSTOMER_NAME} data in ${CUSTOMER_DB}"`
   - Each customer sees their own rendered version

4. **Quick customer context switching**
   - Use project selector to switch between customers
   - Instantly see how rules apply to each customer

### Workflow 4: Migrating Existing Configuration

**Scenario:** You have existing config files and want to centralize them.

1. **Inventory your config files**
   - `.env` files
   - `config.json` files
   - Environment variables

2. **Create project in system**
   - Use existing project identifier
   - Match tech stack to actual setup

3. **Import variables via batch API**
   ```javascript
   const envVars = parseEnvFile('.env');
   const variables = Object.entries(envVars).map(([name, value]) => ({
     variableName: name,
     value: value,
     category: categorizeVar(name),
     description: describeVar(name)
   }));

   await fetch('/api/admin/projects/my-app/variables/batch', {
     method: 'POST',
     headers: { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' },
     body: JSON.stringify({ variables })
   });
   ```

4. **Update governance rules**
   - Replace hardcoded values with `${VARIABLE}` placeholders
   - Test with your project selected
   - Verify all variables are substituted correctly

---

## Best Practices

### Project Organization

✅ **Do:**
- Use consistent ID naming (kebab-case)
- Add detailed descriptions
- Keep tech stack info up to date
- Use metadata for custom fields
- Activate projects only when in use

❌ **Don't:**
- Use special characters in IDs
- Leave descriptions empty
- Create duplicate projects
- Hard-delete projects unless necessary

### Variable Management

✅ **Do:**
- Use descriptive variable names
- Add descriptions to all variables
- Choose appropriate categories
- Set correct data types
- Document variable purpose

❌ **Don't:**
- Use lowercase or mixed-case variable names
- Store sensitive data without encryption
- Create variables you don't need
- Forget to update variables when config changes

### Security

🔒 **Sensitive Variables:**
- Mark with `security` category
- Limit access to variable management
- Rotate credentials regularly
- Consider external secret management for production
- Never commit credentials to version control

🔒 **Access Control:**
- Only grant admin access to trusted users
- Audit variable changes regularly
- Use soft delete to preserve audit trail
- Review variable values before production deployment

### Performance

⚡ **Optimization Tips:**
- Use filters to reduce displayed projects
- Batch variable operations when possible
- Only enable variable substitution when needed
- Keep variable values concise
- Archive inactive projects

---

## Troubleshooting

### Common Issues

#### Issue: Variable Not Substituting

**Symptoms:**
- Rule shows `${VAR_NAME}` in rendered text
- Variable appears to exist in project

**Solutions:**
1. Check variable name is UPPER_SNAKE_CASE
2. Verify variable is active (not deleted)
3. Ensure project is selected in Project Selector
4. Check variable belongs to selected project
5. Verify variable name matches exactly (case-sensitive)

#### Issue: Project Not Appearing in Selector

**Symptoms:**
- Project exists but not in dropdown
- Can't select project in Rule Manager

**Solutions:**
1. Check project is active
2. Verify you're logged in with admin privileges
3. Try refreshing the page
4. Check browser console for errors

#### Issue: Variable Validation Errors

**Symptoms:**
- "Invalid variable name" error
- Can't save variable

**Solutions:**
1. Ensure name is UPPER_SNAKE_CASE
2. Start with uppercase letter (A-Z)
3. Use only letters, numbers, underscores
4. Avoid special characters and hyphens

#### Issue: Can't Delete Project

**Symptoms:**
- Delete button doesn't work
- Error on deletion

**Solutions:**
1. Check you have admin permissions
2. Verify project exists and is not locked
3. Try soft delete first
4. Check browser console for errors

### Getting Help

If you encounter issues:

1. **Check the documentation**
   - API Documentation: `docs/api/PROJECTS_API.md`
   - This user guide

2. **Review the audit log**
   - Navigate to Audit & Analytics
   - Check recent changes to projects/variables

3. **Check browser console**
   - Press F12 to open developer tools
   - Look for error messages in Console tab

4. **Contact support**
   - Provide project ID
   - Include error messages
   - Describe steps to reproduce

---

## FAQ

### General Questions

**Q: What's the difference between a project ID and project name?**
A: The ID is a unique, unchangeable identifier (e.g., `tractatus`). The name is a display label that can be updated (e.g., "Tractatus AI Safety Framework").

**Q: Can I change a project ID after creation?**
A: No, project IDs are permanent. You'll need to create a new project with the desired ID and migrate variables.

**Q: How many projects can I create?**
A: There's no hard limit, but keep it manageable. Consider archiving inactive projects.

**Q: Can multiple projects share the same variables?**
A: No, each project has its own set of variable values. However, variable *names* can be the same across projects (e.g., all projects can have `DB_NAME`).

### Variable Questions

**Q: What happens if I delete a variable that's used in rules?**
A: The variable placeholder (e.g., `${DB_NAME}`) will remain in the rendered text unreplaced.

**Q: Can I use the same variable name in different projects?**
A: Yes! Variables are project-specific. `DB_NAME` in `project-a` is separate from `DB_NAME` in `project-b`.

**Q: How do I rename a variable?**
A: Delete the old variable and create a new one with the desired name. Update any references in rules.

**Q: What's the difference between categories?**
A: Categories are for organization only. They help you filter and group related variables but don't affect functionality.

**Q: Can I use variables in rule metadata or other fields?**
A: Currently, variable substitution only works in rule `text` field. Other fields are planned for future releases.

### Substitution Questions

**Q: Why do some rules show template but no rendered text?**
A: Either no project is selected in the Project Selector, or the rule contains no variables to substitute.

**Q: Do variables work with project-specific rules?**
A: Yes! Both universal and project-specific rules support variable substitution.

**Q: Can I see which variables are used in which rules?**
A: Yes, the rule card shows a count of variables. You can also see the `substitutions` object in the API response.

**Q: What happens with circular variable references?**
A: Variables can't reference other variables. Each variable has a simple string value that's directly substituted.

---

## Appendix

### Keyboard Shortcuts

When using the Project Manager:

- `Esc` - Close open modals
- `Ctrl/Cmd + F` - Focus search box (if implemented)
- `Ctrl/Cmd + N` - New project (if implemented)

### UI Elements Guide

**Project Card Elements:**
- 🟢 **Green badge** - Active project
- ⚫ **Gray badge** - Inactive project
- 🔵 **Blue badge** - Framework technology
- 🟣 **Purple badge** - Database technology
- 🔷 **Indigo badge** - Frontend technology
- 🏷️ **Tag icon** - Variable count
- 📦 **Code icon** - Repository available

**Variable Management Icons:**
- ✏️ **Edit** - Modify variable
- 🗑️ **Delete** - Remove variable
- ➕ **Add** - Create new variable

### Sample Data

Use the seed script to populate sample data:

```bash
npm run seed:projects
```

This creates:
- 4 sample projects (tractatus, family-history, sydigital, example-project)
- 26 sample variables across all projects
- Various categories and data types for testing

---

**Document Version:** 1.0
**Last Updated:** January 15, 2025
**Maintained By:** Tractatus Framework Team

For technical API documentation, see [PROJECTS_API.md](./api/PROJECTS_API.md)