Project Structure

🏗️ BLACKTRAILS PLATFORM - PROJECT STRUCTURE

Last Updated: 18 Dicembre 2025 Version: 2.0 Author: BlackTrails Team

---

📋 INDEX

1. Overview
2. Complete Structure
3. Folder Descriptions
4. Library System
5. Tech Stack

---

🎯 OVERVIEW

BLACKTRAILS PLATFORM is a multi-brand modular platform hosting:

• BlackTrails - Digital Studio (static landing)
• IN-1 - AI Haiku Experience (conversation + database)
• Forest - Haiku Collection (gallery)
• Library - Knowledge Base (RAG system) ✨ NEW

Architecture: Monorepo with brand detection and dynamic routing. Tech Stack: Node.js + Express + EJS + PostgreSQL + pgvector

---

📂 COMPLETE STRUCTURE

BLACKTRAILS-PLATFORM/
│
├── 📁 db/                          # Database Schema & Migrations
│   ├── schema.sql                  # PostgreSQL schema (multi-schema)
│   ├── migrations/                 # Future migration files
│   └── seeds/                      # Seed data (future)
│
├── 📁 docs/                        # 📚 Project Documentation
│   ├── database.md                 # Database architecture
│   ├── structure.md                # This file (directory map)
│   ├── in1_algoritmo.md           # IN-1 algorithm detailed spec
│   └── MASTER_PLAN.md             # Strategic roadmap (moved to /DOCS)
│
├── 📁 library/                     # 📚 Knowledge Base (RAG) ✨ NEW
│   │
│   ├── 📁 public/                  # Public documents (website)
│   │   ├── 📁 it/                  # Italian documents
│   │   │   ├── 📁 filosofia/
│   │   │   │   ├── rhama.md
│   │   │   │   └── rhama-paradigm.md
│   │   │   ├── 📁 progetti/
│   │   │   └── 📁 algoritmi/
│   │   │       └── in1.md
│   │   │
│   │   └── 📁 en/                  # English documents (future)
│   │
│   └── 📁 private/                 # Private documents (internal)
│       ├── 📁 strategie/           # Business strategies
│       │   └── piano-triennale.md
│       └── 📁 finanza/             # Financial documents
│           ├── budget-2025.md
│           └── previsioni-q1.md
│
├── 📁 scripts/                     # 🛠️ Maintenance & Deploy Scripts
│   ├── setup-database.js           # Initialize database
│   ├── check-haikus-schema.js      # Verify haikus schema
│   ├── check-prod-schema.js        # Verify production schema
│   ├── verify-db-v2.js             # Database health check
│   ├── reset-prod-db.js            # Reset production DB (DANGER!)
│   ├── alter-prod-language.js      # Language column migration
│   ├── sync-library.js             # ✨ NEW: Sync library/ → database
│   ├── cloudflare-deploy.js        # Deploy Cloudflare Pages (old)
│   ├── cloudflare-deploy-v2.js     # Deploy Cloudflare Pages (v2)
│   └── deploy-render.js            # Deploy Render.com
│
├── 📁 src/                         # 🏠 Source Code
│   │
│   ├── 📁 engine/                  # ⚙️ Core Platform Logic
│   │   ├── auth.js                 # Authentication (JWT + sessions)
│   │   ├── db.js                   # Database connection pool (PostgreSQL)
│   │   ├── email.js                # Email service (Resend API)
│   │   ├── middleware.js           # Express middleware (CORS, auth, error)
│   │   └── permissions.js          # ACL and permission logic
│   │
│   └── 📁 public/                  # 🌐 Web Application
│       │
│       ├── 📁 public/              # 📦 Static Assets (served via /static/)
│       │   │
│       │   ├── 📁 css/             # 🎨 Stylesheets (modular per brand)
│       │   │   ├── design-system.css       # Common tokens (colors, fonts)
│       │   │   ├── dashboard-common.css    # Dashboard styles (WIP)
│       │   │   ├── 📁 in1/                 # IN-1 CSS
│       │   │   │   └── style.css           # Haiku experience styles
│       │   │   └── 📁 forest/              # Forest CSS
│       │   │       └── style.css           # Forest page styles
│       │   │
│       │   ├── 📁 js/              # ⚡ JavaScript Modules (vanilla)
│       │   │   ├── lucide.min.js           # Icon library (minified)
│       │   │   ├── marked.min.js           # Markdown parser (minified)
│       │   │   ├── 📁 in1/                 # IN-1 JavaScript Modules
│       │   │   │   ├── tree.js             # Tree canvas animation (GSAP)
│       │   │   │   ├── chat-ui.js          # Chat UI logic (loader morph)
│       │   │   │   ├── haiku.js            # AI conversation logic (API)
│       │   │   │   └── home.js             # Landing page logic
│       │   │   └── 📁 forest/              # Forest JavaScript Modules
│       │   │       └── forest.js           # Forest logic (placeholder)
│       │   │
│       │   ├── 📁 favicons/        # 🖼️ Icons & Manifests
│       │   │   ├── favicon.ico             # Legacy favicon
│       │   │   ├── favicon.svg             # SVG favicon (modern)
│       │   │   ├── apple-touch-icon.png    # iOS icon (180x180)
│       │   │   ├── icon-192.png            # Android icon (192x192)
│       │   │   ├── icon-512.png            # Android icon (512x512)
│       │   │   └── site.webmanifest        # PWA manifest
│       │   │
│       │   ├── 📁 img/             # 🖼️ Images (empty, future assets)
│       │   │
│       │   └── 📁 content/         # 📝 Markdown Content (legal pages)
│       │       ├── about.md                # About page
│       │       ├── privacy.md              # Privacy policy
│       │       └── terms.md                # Terms of service
│       │
│       ├── 📁 routes/              # 🛤️ Express Routes (brand-based)
│       │   ├── landing.js                  # Landing pages (BlackTrails, IN-1, Forest)
│       │   ├── in1.js                      # IN-1 API (/api/in1/*)
│       │   ├── auth.js                     # Auth routes (/auth/*)
│       │   ├── library.js                  # ✨ NEW: Library API (/api/library/*)
│       │   ├── gcore.js                    # GCore routes (WIP)
│       │   └── elements.js                 # Elements routes (placeholder)
│       │
│       ├── 📁 views/               # 🎨 EJS Templates
│       │   │
│       │   ├── 📁 landing/         # Landing Pages (per brand)
│       │   │   ├── 📁 blacktrails/ # BlackTrails Landing
│       │   │   │   └── index.ejs           # Homepage BlackTrails (static)
│       │   │   │
│       │   │   ├── 📁 in1/         # IN-1 Landing & Chat
│       │   │   │   ├── index.ejs           # IN-1 Homepage (tree + form)
│       │   │   │   ├── haiku.ejs           # IN-1 Chat Experience
│       │   │   │   ├── vision.ejs          # Vision page
│       │   │   │   └── legal.ejs           # Legal page
│       │   │   │
│       │   │   ├── 📁 forest/      # Forest Landing
│       │   │   │   └── index.ejs           # Forest Gallery (3 haiku cards)
│       │   │   │
│       │   │   ├── 📁 gcore/       # GCore Pages (WIP)
│       │   │   │   ├── index.ejs           # GCore homepage
│       │   │   │   └── (8 other pages)
│       │   │   │
│       │   │   └── 📁 elements/    # Elements Pages (placeholder)
│       │   │
│       │   ├── 📁 app-user/        # User Dashboard (WIP)
│       │   │
│       │   └── 📁 partials/        # EJS Partials Reusable (empty)
│       │
│       ├── 📁 utils/               # 🧰 Utility Modules
│       │   ├── almaHaiku.js                # AI Haiku Generation (Anthropic Claude)
│       │   └── emotionAnalyzer.js          # Sentiment Analysis (input safety)
│       │
│       └── server.js               # 🚀 Express Server Entry Point
│
├── 📁 tests/                       # 🧪 Test Suite
│   ├── test-alma-v2-flow.js        # Test conversation flow
│   ├── test-emotion-analyzer.js    # Test sentiment analyzer
│   ├── test-natura-vocabolario.js  # Test nature vocabulary
│   ├── test-safety-keyword.js      # Test keyword safety
│   ├── test-gsap.html              # Test GSAP animation
│   └── test-*.json                 # Sample conversation turns (mock data)
│
├── package.json                    # 📦 Dependencies & Scripts
├── package-lock.json               # 🔒 Lockfile
├── .env                            # 🔐 Environment variables (gitignored)
├── .gitignore                      # 🚫 Git ignore rules
├── README.md                       # 📖 Project README
└── server.log                      # 📝 Server logs (gitignored)

---

📚 FOLDER DESCRIPTIONS

1. /db/ - Database

PostgreSQL schema for the entire platform. Includes:

• Multi-schema architecture (auth, in1, elements, library, finance)
• Migration files (future)
• Seed data (future)

Key file: schema.sql

---

2. /docs/ - Documentation 📚

Technical project documentation:

• database.md - Complete database architecture
• structure.md - This file (directory map)
• in1_algoritmo.md - IN-1 algorithm detailed specification
• API docs (future)

---

3. /library/ - Knowledge Base 📚 ✨ NEW

Centralized knowledge management system with:

• Public documents: Website content (philosophy, projects, algorithms)
• Private documents: Internal docs (strategies, finance, planning)
• i18n support: Multilingual (it/en/es/fr/de)
• RAG integration: Embeddings for semantic search

Structure:

library/
├── public/
│   ├── it/                         # Italian public docs
│   │   ├── filosofia/              # Philosophy
│   │   │   ├── rhama.md
│   │   │   └── rhama-paradigm.md
│   │   ├── progetti/               # Projects
│   │   └── algoritmi/              # Algorithms
│   │       └── in1.md
│   │
│   └── en/                         # English public docs (future)
│
└── private/
    ├── strategie/                  # Business strategies
    │   └── piano-triennale.md
    └── finanza/                    # Financial documents
        ├── budget-2025.md
        └── previsioni-q1.md

Sync Process:

npm run sync-library

1. Scans library/public/ and library/private/
2. Extracts frontmatter metadata (title, category, tags, language)
3. Generates slugs from filenames
4. Calculates MD5 hash for change detection
5. Inserts/updates library.documents table
6. Logs sync results

Database Integration:

• Table: library.documents
• Columns: slug, title, category, content, language, translation_id, public, metadata
• Indexes: slug, category, language, translation_id, content_hash

---

4. /scripts/ - Utility Scripts 🛠️

Node.js scripts for maintenance and deployment:

Script	Purpose
setup-database.js	Initialize database from schema.sql
check-*.js	Health checks and schema verification
verify-db-v2.js	Connection test and integrity check
sync-library.js	✨ Sync library/ folder to database
reset-prod-db.js	⚠️ Reset production (DANGER)
alter-prod-language.js	Schema migration (add language column)
cloudflare-deploy*.js	Deploy to Cloudflare Pages
deploy-render.js	Deploy to Render.com

Execution: node scripts/<script-name>.js

---

5. /src/engine/ - Core Logic ⚙️

Platform core modules (shared across brands):

File	Responsibility
auth.js	JWT generation, session management, user authentication
db.js	PostgreSQL connection pool (pg), query helpers
email.js	Email sending via Resend API
middleware.js	Express middleware (CORS, auth check, error handler)
permissions.js	ACL (Access Control List), role-based permissions

Imported by: server.js, routes

---

6. /src/public/public/ - Static Assets 📦

Served via Express: app.use('/static', express.static('src/public/public')) Public URL: https://domain.com/static/css/in1/style.css

6.1 /css/ - Stylesheets 🎨

Modular CSS organized by brand:

• design-system.css - Common tokens (—accent, —font-display)
• dashboard-common.css - Dashboard styles (WIP)
• in1/style.css - IN-1 chat experience (tree, loader, final haiku)
• forest/style.css - Forest gallery (haiku cards, navbar, footer)

Architecture: Mobile-first, BEM naming, CSS Variables

6.2 /js/ - JavaScript Modules ⚡

Vanilla JavaScript (NO frameworks). Modular with IIFE pattern.

IN-1 Modules (/js/in1/):

File	Responsibility
tree.js	Canvas animation (fractal tree, GSAP growth)
chat-ui.js	Chat UI logic (loader morphing, typewriter effect)
haiku.js	AI conversation (API calls, state management)
home.js	Landing page logic (form, ROOT DETECTED, nav)

Libraries:

• lucide.min.js - Icon library
• marked.min.js - Markdown parser

---

7. /src/public/routes/ - Express Routes 🛤️

Modular routing for brand detection:

File	Route Path	Brand	Purpose
landing.js	/	BlackTrails, IN-1, Forest	Landing pages (switch on req.brand)
in1.js	/api/in1/*	IN-1	API endpoints (chat, haiku generation)
library.js	/api/library/*	Library	✨ Document search and RAG queries
auth.js	/auth/*	-	Login, signup, logout (future)
gcore.js	/gcore/*	GCore	GCore pages (WIP)
elements.js	/elements/*	Elements	Component library (placeholder)

Brand Detection Logic (server.js):

// Development: ?brand=in1|forest|blacktrails
if (process.env.NODE_ENV === 'development') {
    req.brand = req.query.brand || 'blacktrails';
}

// Production: domain-based
if (req.hostname === 'in-1.it') req.brand = 'in1';
else if (req.hostname === 'forest.in-1.it') req.brand = 'forest';
else req.brand = 'blacktrails';

---

8. /src/public/views/ - EJS Templates 🎨

Server-Side Rendering with EJS:

8.1 /landing/ - Landing Pages

Organized by brand:

BlackTrails (/landing/blacktrails/):

• index.ejs - Homepage (static, company portfolio)

IN-1 (/landing/in1/):

• index.ejs - Landing page (tree animation + prompt form)
• haiku.ejs - Chat experience (AI conversation → haiku)
• vision.ejs - Vision page (mission, values)
• legal.ejs - Legal page (privacy, terms)

Forest (/landing/forest/):

• index.ejs - Haiku gallery (3 cards hardcoded, future DB)

GCore (/landing/gcore/):

• 8 pages (index, about, business, contact, docs, legal, privacy, terms, vision)
• Status: WIP (placeholder)

---

9. /src/public/utils/ - Utility Modules 🧰

File	Responsibility
almaHaiku.js	AI Haiku Generation Engine (Anthropic Claude API)
emotionAnalyzer.js	Sentiment Analysis + Safety Filter (input validation)

almaHaiku.js:

• Manages 5 conversation turns
• Analyzes emotional depth
• Generates final haiku (5-7-5 syllables)
• Multi-language support (IT/EN/ES/FR/DE)

emotionAnalyzer.js:

• Detects sentiment (positive/negative/neutral)
• Blocks dangerous keywords (hate speech, violence)
• Score 0-100 (emotional depth)

---

10. /src/public/server.js - Entry Point 🚀

Express server main entry. Responsibilities:

• Middleware setup (CORS, body-parser, static files)
• Brand detection (development query param, production hostname)
• Route mounting (landing, in1, library, auth, gcore, elements)
• Error handling (404, 500)
• Server startup (port 3000 local, process.env.PORT prod)

Startup:

# Development
npm run dev       # nodemon src/public/server.js

# Production
npm start         # node src/public/server.js

---

🔧 TECH STACK

Backend

• Runtime: Node.js v20+
• Framework: Express.js 4.x
• Template Engine: EJS
• Database: PostgreSQL 17 (Neon.tech)
• ORM: pg (connection pool)
• AI: Anthropic Claude API (Sonnet 4.5)
• Email: Resend API
• Auth: JWT + sessions

Frontend

• JavaScript: Vanilla ES6+ (no frameworks)
• CSS: Modular, mobile-first, BEM naming
• Icons: Lucide (minified)
• Animations: GSAP 3.x
• Markdown: marked.js

Database Extensions

• pgvector: Embeddings for RAG (1536 dimensions)
• pg_trgm: Trigram similarity search (future)

DevOps

• Hosting: Render.com (production)
• CDN: Cloudflare Pages (static assets)
• Monitoring: Server logs (Winston) - future
• CI/CD: GitHub Actions (future)

---

📊 RECENT UPDATES

Library System (18 Dec 2025) ✨

1. Created /library/ structure:

   • public/ for website content
   • private/ for internal documents
   • i18n folders (it/en)

2. Implemented sync script:

   npm run sync-library

   • Auto-detects language from frontmatter
   • Links translated documents via translation_id
   • Updates database with content + metadata

3. Database integration:

   • Added language column to library.documents
   • Added translation_id for linking versions
   • Created indexes for performance

4. Current content:

   • Philosophy: Rhama, Rhama Paradigm (IT)
   • Algorithms: IN-1 flow (IT)
   • Private: Business strategies, finance docs

---

🚀 USEFUL COMMANDS

# Development
npm run dev                        # Start server with nodemon (hot reload)

# Production
npm start                          # Start Node.js server

# Database
node scripts/setup-database.js     # Initialize database
node scripts/verify-db-v2.js       # Verify connection
node scripts/sync-library.js       # Sync library/ to database

# Deploy
node scripts/deploy-render.js      # Deploy to Render.com
node scripts/cloudflare-deploy-v2.js # Deploy to Cloudflare Pages

# Test
node tests/test-alma-v2-flow.js    # Test conversation flow
node tests/test-emotion-analyzer.js # Test sentiment analysis

---

📞 CONTACTS

BlackTrails Team Email: francesco.pelosio@gmail.com Website: https://blacktrails.com

---

End of Document 🌲✨