feat: initialize tractatus project with complete directory structure

- Create comprehensive project structure (29 directories)
- Add CLAUDE.md with project context and conventions
- Add package.json with dependencies and scripts
- Add .gitignore and .env.example
- Add README.md with project overview
- Configure ports: MongoDB 27017, Application 9000
- Establish Tractatus governance framework baseline
- Document Te Tiriti approach and indigenous perspective
- Set up infrastructure for Phase 1 implementation

Project Status: Development - Phase 1 Foundation Complete
Next: MongoDB instance setup and systemd service configuration
This commit is contained in:
TheFlow 2025-10-06 23:26:26 +13:00
commit 4445b0e8d0
8 changed files with 4937 additions and 0 deletions

33
.env.example Normal file
View file

@ -0,0 +1,33 @@
# Application
NODE_ENV=development
PORT=9000
APP_NAME=Tractatus
# MongoDB
MONGODB_URI=mongodb://localhost:27017/tractatus_dev
MONGODB_PORT=27017
MONGODB_DB=tractatus_dev
# JWT Authentication
JWT_SECRET=generate_a_secure_random_secret_key_here
JWT_EXPIRY=7d
# Admin
ADMIN_EMAIL=john.stroh.nz@pm.me
# Claude API (Phase 2+)
# CLAUDE_API_KEY=your_anthropic_api_key_here
# CLAUDE_MODEL=claude-sonnet-4-5
# Logging
LOG_LEVEL=info
LOG_FILE=logs/app.log
# Feature Flags
ENABLE_AI_CURATION=false
ENABLE_MEDIA_TRIAGE=false
ENABLE_CASE_SUBMISSIONS=false
# Security
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

48
.gitignore vendored Normal file
View file

@ -0,0 +1,48 @@
# Dependencies
node_modules/
package-lock.json
# Environment variables
.env
.env.local
.env.*.local
# Logs
logs/
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
# MongoDB data
data/mongodb/*
!data/mongodb/.gitkeep
# Generated files
public/downloads/*.pdf
public/downloads/*.epub
public/downloads/*.docx
# IDE
.vscode/
.idea/
*.swp
*.swo
*~
# OS
.DS_Store
Thumbs.db
# Testing
coverage/
.nyc_output/
# Build
dist/
build/
# Temporary files
tmp/
temp/
*.tmp

416
CLAUDE.md Normal file
View file

@ -0,0 +1,416 @@
# Tractatus AI Safety Framework Website - Project Context
**Project Name:** Tractatus Website Platform
**Domain:** mysy.digital
**Repository:** GitHub (primary) + Codeberg/Gitea (mirrors)
**Status:** Development - Phase 1 Implementation
**Created:** 2025-10-06
**Primary Developer:** Claude Code (Anthropic Sonnet 4.5)
**Project Owner:** John Stroh
---
## ⚠️ Critical: Project Isolation
**THIS IS A SEPARATE PROJECT FROM family-history AND sydigital**
- **Separate MongoDB instance**: Port 27017, database `tractatus_dev`
- **Separate application port**: 9000
- **Separate Git repository**: Local + GitHub account
- **Separate systemd services**: mongodb-tractatus.service, tractatus.service
- **No shared code/data**: Patterns may be adapted, but no dependencies
**Sessions must maintain clear separation.** Always verify which project context you're in.
---
## Project Purpose
Build a world-class platform demonstrating the **Tractatus-Based LLM Safety Framework** through:
1. **Three Audience Paths**: Researcher, Implementer, Advocate
2. **AI-Powered Features**: Blog curation, media triage, case studies (all with human oversight)
3. **Interactive Demonstrations**: Classification, 27027 incident, boundary enforcement
4. **Dogfooding**: The website implements Tractatus to govern its own AI operations
5. **Values Alignment**: Sovereignty, Transparency, Harmlessness, Community
**Timeline:** 3-4 months for complete Phase 1 local prototype (no rush, no shortcuts, world-class quality)
---
## Technical Architecture
### Infrastructure
- **MongoDB**: Port 27017, database `tractatus_dev`
- **Application**: Node.js/Express on port 9000
- **WebSocket**: Port 9001 (if needed)
- **Data Directory**: `/home/theflow/projects/tractatus/data/mongodb`
- **Logs**: `/home/theflow/projects/tractatus/logs/`
### Technology Stack
- **Backend**: Node.js 18+, Express 4.x, MongoDB 7+
- **Frontend**: Vanilla JavaScript, Tailwind CSS (no framework dependency)
- **Authentication**: JWT for admin/moderation
- **AI Integration**: Claude API (Sonnet 4.5) - Phase 2+
- **File Storage**: GridFS for PDFs, documents
- **Testing**: Jest + Supertest
### Database Collections
```javascript
tractatus_dev.documents // Technical papers, framework docs
tractatus_dev.blog_posts // AI-curated, human-approved
tractatus_dev.media_inquiries // Press/media with AI triage
tractatus_dev.case_submissions // Community case studies
tractatus_dev.resources // External links, aligned projects
tractatus_dev.moderation_queue // Human oversight queue
tractatus_dev.users // Admin accounts
tractatus_dev.citations // Academic citation tracking
tractatus_dev.translations // Multi-language content (future)
tractatus_dev.koha_donations // Phase 3
```
---
## Tractatus Framework Governance
**This project dogfoods the Tractatus framework** - all AI actions are governed by:
### Core Services (to be implemented)
1. **InstructionPersistenceClassifier** - Classifies actions by quadrant (STR/OPS/TAC/SYS/STO)
2. **CrossReferenceValidator** - Validates AI actions against explicit instructions
3. **BoundaryEnforcer** - Ensures AI never makes values decisions without human approval
4. **ContextPressureMonitor** - Detects conditions that increase error probability
5. **MetacognitiveVerifier** - AI self-checks reasoning before proposing actions
### Quadrant Mapping for Website Functions
| Function | Quadrant | Human Oversight | Example |
|----------|----------|-----------------|---------|
| Mission/values changes | STRATEGIC | Mandatory approval | "Always prioritize privacy" |
| Blog editorial guidelines | OPERATIONAL | Quarterly review | "All posts must cite sources" |
| Publish approved post | TACTICAL | Pre-approved | Execute after human approval |
| Technical config | SYSTEM | Technical review | MongoDB ports, API keys |
| AI suggests blog topics | STOCHASTIC | Always human approval | "Write about GDPR" |
**Critical:** All AI content suggestions require human approval. No AI action crosses into values territory without explicit human decision.
---
## Governance Documents
Located in `/home/theflow/projects/tractatus/governance/` (to be created):
- **TRA-VAL-0001**: Tractatus Core Values (adapted from STR-VAL-0001)
- **TRA-GOV-0001**: Strategic Review Protocol (adapted from STR-GOV-0001)
- **TRA-GOV-0002**: Values Alignment Framework (adapted from STR-GOV-0002)
- **TRA-GOV-0003**: AI Boundary Enforcement Policy
- **TRA-GOV-0004**: Human Oversight Requirements
**Reference:** Source documents in `/home/theflow/projects/sydigital/strategic/`
---
## Te Tiriti & Indigenous Perspective
### Strategic Commitment
The framework acknowledges **Te Tiriti o Waitangi** and indigenous leadership in digital sovereignty.
### Implementation Approach
- **Respect without tokenism**: Follow documented indigenous data sovereignty principles (CARE Principles)
- **No premature engagement**: Do not approach Māori organizations until we have something valuable to offer
- **Well-documented standards**: Use published research and frameworks (Te Mana Raraunga, CARE Principles)
- **Baseline integration**: Te Tiriti forms part of strategic foundation, not dominant cultural overlay
### Content Placement
- Footer acknowledgment (subtle, respectful)
- `/about/values` page (detailed explanation)
- Resource directory (links to Māori data sovereignty organizations)
- No meetings/consultations until post-launch
---
## Development Conventions
### Code Style
- **ES6+ JavaScript**: Modern syntax, async/await patterns
- **Modular architecture**: Small, focused functions/classes
- **Explicit naming**: No abbreviations, clear intent
- **Comments**: Explain WHY, not WHAT
- **Error handling**: Comprehensive try/catch, meaningful error messages
### File Naming
- **Routes**: `src/routes/blog.routes.js`
- **Controllers**: `src/controllers/blog.controller.js`
- **Models**: `src/models/BlogPost.model.js`
- **Services**: `src/services/BlogCuration.service.js`
- **Middleware**: `src/middleware/auth.middleware.js`
- **Tests**: `tests/unit/blog.test.js`
### Git Conventions
- **Commits**: Conventional commits format
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation
- `refactor:` Code restructure
- `test:` Test additions
- `chore:` Maintenance
- **Branches**: `feature/blog-curation`, `fix/auth-token`, `docs/api-reference`
- **No commits to main**: Always use feature branches
### Environment Variables
```bash
# Application
NODE_ENV=development
PORT=9000
APP_NAME=Tractatus
# MongoDB
MONGODB_URI=mongodb://localhost:27017/tractatus_dev
MONGODB_PORT=27017
# JWT
JWT_SECRET=<generate_secure_secret>
JWT_EXPIRY=7d
# Claude API (Phase 2+)
CLAUDE_API_KEY=<anthropic_api_key>
CLAUDE_MODEL=claude-sonnet-4-5
# Admin
ADMIN_EMAIL=john.stroh.nz@pm.me
```
---
## Directory Structure
```
/home/theflow/projects/tractatus/
├── .claude/ # Claude Code project config
├── .git/ # Git repository
├── docs/ # Source markdown documents
│ ├── markdown/ # Raw markdown files (migration source)
│ └── governance/ # TRA-VAL-*, TRA-GOV-* documents
├── public/ # Frontend assets
│ ├── css/
│ │ └── tailwind.css
│ ├── js/
│ │ ├── components/ # Reusable UI components
│ │ ├── demos/ # Interactive demonstrations
│ │ └── utils/
│ ├── images/
│ └── downloads/ # Generated PDFs
├── src/ # Backend code
│ ├── server.js # Express app entry point
│ ├── routes/
│ │ ├── docs.routes.js
│ │ ├── blog.routes.js
│ │ ├── media.routes.js
│ │ ├── cases.routes.js
│ │ ├── resources.routes.js
│ │ ├── admin.routes.js
│ │ └── demo.routes.js
│ ├── controllers/
│ ├── models/
│ │ ├── Document.model.js
│ │ ├── BlogPost.model.js
│ │ ├── MediaInquiry.model.js
│ │ ├── CaseSubmission.model.js
│ │ ├── ModerationQueue.model.js
│ │ └── User.model.js
│ ├── middleware/
│ │ ├── auth.middleware.js
│ │ ├── validation.middleware.js
│ │ └── tractatus/ # Framework enforcement
│ │ ├── classifier.middleware.js
│ │ ├── validator.middleware.js
│ │ └── boundary.middleware.js
│ ├── services/
│ │ ├── ClaudeAPI.service.js
│ │ ├── InstructionClassifier.service.js
│ │ ├── CrossReferenceValidator.service.js
│ │ ├── BoundaryEnforcer.service.js
│ │ ├── ContextPressureMonitor.service.js
│ │ ├── MetacognitiveVerifier.service.js
│ │ ├── BlogCuration.service.js
│ │ ├── MediaTriage.service.js
│ │ ├── DocumentProcessor.service.js
│ │ └── ModerationQueue.service.js
│ ├── utils/
│ │ ├── db.util.js
│ │ ├── jwt.util.js
│ │ ├── markdown.util.js
│ │ └── logger.util.js
│ └── config/
│ ├── database.config.js
│ └── app.config.js
├── scripts/ # Setup & migration
│ ├── init-db.js # Create collections, indexes
│ ├── migrate-documents.js # Import markdown content
│ ├── generate-pdfs.js # PDF export
│ ├── seed-admin.js # Create admin user
│ └── start-dev.sh # Development startup
├── tests/
│ ├── unit/
│ ├── integration/
│ └── security/
├── data/ # MongoDB data directory
│ └── mongodb/
├── logs/ # Application & MongoDB logs
│ ├── app.log
│ └── mongodb.log
├── .env.example # Template environment variables
├── .gitignore
├── package.json
├── package-lock.json
├── README.md
├── CLAUDE.md # This file
└── LICENSE
```
---
## Phase 1 Deliverables (3-4 Months)
**Must-Have for Complete Prototype:**
1. ✅ **Infrastructure**
- MongoDB instance (port 27017)
- Express application (port 9000)
- Systemd services
- Directory structure
2. **Core Features**
- Document migration pipeline
- Three audience paths (Researcher/Implementer/Advocate)
- Documentation viewer with search
- About/values pages (Te Tiriti acknowledgment)
3. **Tractatus Governance Services**
- InstructionPersistenceClassifier
- CrossReferenceValidator
- BoundaryEnforcer
- ContextPressureMonitor
- MetacognitiveVerifier
4. **AI-Powered Features** (with human oversight)
- Blog curation system
- Media inquiry triage
- Case study submission portal
- Resource directory curation
5. **Interactive Demonstrations**
- Instruction classification demo
- 27027 incident visualizer
- Boundary enforcement simulator
6. **Human Oversight**
- Moderation queue dashboard
- Admin authentication
- Approval workflows
7. **Quality Assurance**
- Comprehensive testing suite
- Security audit
- Performance optimization
- Accessibility compliance (WCAG)
**Not in Phase 1:**
- Production deployment (OVHCloud)
- Domain configuration (mysy.digital)
- ProtonBridge email integration
- Koha donations (Phase 3)
- Public launch
---
## Success Criteria
**Technical Excellence:**
- Clean, maintainable code
- 80%+ test coverage
- <2s page load times
- WCAG AA accessibility
- Zero security vulnerabilities
- Complete API documentation
**Framework Demonstration:**
- All AI actions governed by Tractatus
- Human oversight for values-sensitive content
- Boundary enforcement working
- Classification system accurate
- Moderation queue functional
**Content Quality:**
- All documents migrated correctly
- Three audience paths distinct and clear
- Interactive demos working
- Blog system ready for Phase 2
- No placeholder/fake data
---
## Human Approval Required For:
**All Major Decisions:**
- Architectural changes
- Database schema modifications
- Security implementations
- Third-party integrations
- Cost-incurring services
**Content & Values:**
- Governance document adaptations (TRA-VAL-*, TRA-GOV-*)
- Te Tiriti acknowledgment wording
- About/mission pages
- Editorial guidelines
- Any values-sensitive content
**Phase Transitions:**
- Completion of Phase 1 prototype
- Decision to proceed to production deployment
- Budget approval for Claude API (Phase 2)
- Launch timing and strategy
---
## Links & References
**Source Documents:**
- `/home/theflow/projects/tractatus/Tractatus-Website-Complete-Specification-v2.0.md`
- `/home/theflow/projects/tractatus/ClaudeWeb conversation transcription.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/STO-INN-0010-tractatus-llm-architecture-safety-framework-i1.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/anthropic-submission/technical-proposal.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/anthropic-submission/appendix-a-code-examples.md`
**Governance References:**
- `/home/theflow/projects/sydigital/strategic/values-principles/STR-VAL-0001-core-values-principles-v1-0.md`
- `/home/theflow/projects/sydigital/strategic/governance/STR-GOV-0001-strategic-review-protocol-v1-0.md`
- `/home/theflow/projects/sydigital/strategic/governance/STR-GOV-0002-values-alignment-framework-v1-0.md`
**Framework Documentation:**
- `/home/theflow/projects/sydigital/strategic/frameworks/STR-FRM-0001-agentic-workflow-framework-v1-0.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/STO-INN-0002-agentic-organizational-structure-whitepaper-i2.md`
---
## Session Reminders
**Always:**
- Verify you're in `/home/theflow/projects/tractatus` context
- Check MongoDB port 27017, application port 9000
- No shortcuts, no fake data, world-class quality
- Human approval for major decisions
- Update todo list as tasks progress
**Never:**
- Mix tractatus code with family-history or sydigital
- Make values decisions without human approval
- Deploy to production during Phase 1
- Rush implementation to meet arbitrary deadlines
- Use placeholder/lorem ipsum content
---
**Last Updated:** 2025-10-06
**Next Review:** After Phase 1 completion

File diff suppressed because it is too large Load diff

203
README.md Normal file
View file

@ -0,0 +1,203 @@
# Tractatus AI Safety Framework Website
**Status:** Development - Phase 1 Implementation
**Domain:** mysy.digital
**Project Start:** 2025-10-06
---
## Overview
A world-class platform demonstrating the **Tractatus-Based LLM Safety Framework** through three audience paths (Researcher, Implementer, Advocate), AI-powered features with human oversight, and interactive demonstrations.
**Key Innovation:** The website implements the Tractatus framework to govern its own AI operations (dogfooding).
---
## Project Structure
```
tractatus/
├── docs/ # Source markdown & governance documents
├── public/ # Frontend assets (CSS, JS, images)
├── src/ # Backend code (Express, MongoDB)
│ ├── routes/ # API route handlers
│ ├── controllers/ # Business logic
│ ├── models/ # MongoDB models
│ ├── middleware/ # Express middleware
│ │ └── tractatus/ # Framework enforcement
│ ├── services/ # Core services (AI, governance)
│ └── utils/ # Utility functions
├── scripts/ # Setup & migration scripts
├── tests/ # Test suites (unit, integration, security)
├── data/ # MongoDB data directory
└── logs/ # Application & MongoDB logs
```
---
## Quick Start
### Prerequisites
- Node.js 18+
- MongoDB 7+
- Git
### Installation
```bash
# Clone repository (once GitHub account is set up)
cd /home/theflow/projects/tractatus
# Install dependencies
npm install
# Copy environment variables
cp .env.example .env
# Edit .env with your configuration
# Initialize database
npm run init:db
# Migrate documents
npm run migrate:docs
# Create admin user
npm run seed:admin
# Start development server
npm run dev
```
The application will be available at `http://localhost:9000`
---
## Technical Stack
- **Backend:** Node.js, Express, MongoDB
- **Frontend:** Vanilla JavaScript, Tailwind CSS
- **Authentication:** JWT
- **AI Integration:** Claude API (Sonnet 4.5) - Phase 2+
- **Testing:** Jest, Supertest
---
## Infrastructure
- **MongoDB Port:** 27017
- **Application Port:** 9000
- **Database:** tractatus_dev
- **Systemd Service:** mongodb-tractatus.service, tractatus.service
---
## Phase 1 Deliverables (3-4 Months)
**Must-Have for Complete Prototype:**
- [x] Infrastructure setup
- [ ] Document migration pipeline
- [ ] Three audience paths (Researcher/Implementer/Advocate)
- [ ] Tractatus governance services (Classifier, Validator, Boundary Enforcer)
- [ ] AI-curated blog with human oversight
- [ ] Media inquiry triage system
- [ ] Case study submission portal
- [ ] Resource directory
- [ ] Interactive demonstrations (classification, 27027, boundary enforcement)
- [ ] Human oversight dashboard
- [ ] Comprehensive testing suite
---
## Development Workflow
### Running Tests
```bash
npm test # All tests with coverage
npm run test:unit # Unit tests only
npm run test:integration # Integration tests
npm run test:security # Security tests
npm run test:watch # Watch mode
```
### Code Quality
```bash
npm run lint # Check code style
npm run lint:fix # Fix linting issues
```
### Database Operations
```bash
npm run init:db # Initialize database & indexes
npm run migrate:docs # Import markdown documents
npm run generate:pdfs # Generate PDF downloads
```
---
## Governance
This project adheres to the Tractatus framework principles:
- **Sovereignty & Self-determination:** No tracking, user control, open source
- **Transparency & Honesty:** Public moderation queue, AI reasoning visible
- **Harmlessness & Protection:** Privacy-first design, security audits
- **Community & Accessibility:** WCAG compliance, three audience paths
All AI actions are governed by:
1. InstructionPersistenceClassifier
2. CrossReferenceValidator
3. BoundaryEnforcer
4. ContextPressureMonitor
5. MetacognitiveVerifier
---
## Human Approval Required
**All major decisions require human approval:**
- Architectural changes
- Database schema modifications
- Security implementations
- Third-party integrations
- Values-sensitive content
- Cost-incurring services
**See:** `CLAUDE.md` for complete project context and conventions
---
## Te Tiriti & Indigenous Perspective
This project acknowledges **Te Tiriti o Waitangi** and indigenous leadership in digital sovereignty. Implementation follows documented indigenous data sovereignty principles (CARE Principles) with respect and without tokenism.
**No premature engagement:** We will not approach Māori organizations until we have something valuable to offer post-launch.
---
## Links & Resources
- **Project Context:** `CLAUDE.md`
- **Specification:** `Tractatus-Website-Complete-Specification-v2.0.md`
- **Framework Documentation:** `/home/theflow/projects/sydigital/stochastic/innovation-exploration/`
- **Governance References:** `/home/theflow/projects/sydigital/strategic/`
---
## License
MIT License - See LICENSE file for details
---
## Contact
**Project Owner:** John Stroh
**Email:** john.stroh.nz@pm.me
**Repository:** GitHub (primary) + Codeberg/Gitea (mirrors)
---
**Last Updated:** 2025-10-06
**Next Milestone:** Complete MongoDB setup and systemd service

File diff suppressed because it is too large Load diff

0
data/mongodb/.gitkeep Normal file
View file

56
package.json Normal file
View file

@ -0,0 +1,56 @@
{
"name": "tractatus-website",
"version": "0.1.0",
"description": "Tractatus-Based LLM Safety Framework website platform",
"main": "src/server.js",
"scripts": {
"start": "node src/server.js",
"dev": "nodemon src/server.js",
"test": "jest --coverage",
"test:watch": "jest --watch",
"test:unit": "jest tests/unit",
"test:integration": "jest tests/integration",
"test:security": "jest tests/security",
"lint": "eslint src/ tests/",
"lint:fix": "eslint src/ tests/ --fix",
"migrate:docs": "node scripts/migrate-documents.js",
"init:db": "node scripts/init-db.js",
"seed:admin": "node scripts/seed-admin.js",
"generate:pdfs": "node scripts/generate-pdfs.js"
},
"keywords": [
"ai-safety",
"llm",
"tractatus",
"digital-sovereignty",
"ai-governance"
],
"author": "John Stroh <john.stroh.nz@pm.me>",
"license": "MIT",
"dependencies": {
"express": "^4.18.2",
"mongodb": "^6.3.0",
"dotenv": "^16.3.1",
"jsonwebtoken": "^9.0.2",
"bcrypt": "^5.1.1",
"marked": "^11.0.0",
"highlight.js": "^11.9.0",
"sanitize-html": "^2.11.0",
"express-rate-limit": "^7.1.5",
"helmet": "^7.1.0",
"cors": "^2.8.5",
"winston": "^3.11.0",
"validator": "^13.11.0"
},
"devDependencies": {
"nodemon": "^3.0.2",
"jest": "^29.7.0",
"supertest": "^6.3.3",
"eslint": "^8.56.0",
"@anthropic-ai/sdk": "^0.9.1"
},
"engines": {
"node": ">=18.0.0",
"npm": ">=9.0.0"
}
}