tractatus/docs/USER_GUIDE_PROJECTS.md

Multi-Project Governance - User Guide

Version: 1.0 Last Updated: January 15, 2025

---

Table of Contents

1. Introduction
2. Getting Started
3. Managing Projects
4. Managing Variables
5. Viewing Rules with Variable Substitution
6. Common Workflows
7. Best Practices
8. Troubleshooting
9. 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:

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 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

   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:

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