Architecture Overview

Questi contenuti non sono ancora disponibili nella tua lingua.

Architecture Overview

Complete technical architecture of the BlackTrails platform, organized as a Modular Monolith with isolated brand modules sharing a common core.

System Diagram

graph TD
    subgraph PublicLayer[Public Layer - Port 3000]
        Server[server.js Entry Point]
        BrandDetection[Brand Detection Middleware]
        StaticAssets[Static Assets]
    end
    
    subgraph CoreLayer[Core Layer - Shared Services]
        CoreDB[db.js - PostgreSQL Client]
        CoreAuth[auth.js - Authentication]
        CoreEmail[email.js - Resend Integration]
        CoreMiddleware[middleware.js - Express Stack]
        CorePerms[permissions.js - Authorization]
    end
    
    subgraph BrandModules[Brand Modules - Isolated]
        subgraph In1Module[IN-1 AI Platform]
            In1Routes[routes.js]
            In1Views[views/ - 4 files]
            In1Services[services/ - AI Engine]
            In1Alma[Alma Service]
            In1Poeta[Poeta Service]
            In1Orchestrator[Orchestrator]
        end
        
        subgraph GcoreModule[G-CORE Design System]
            GcoreRoutes[routes.js]
            GcoreViews[views/ - 9 files]
        end
        
        subgraph ForestModule[Forest Landing]
            ForestRoutes[routes.js]
            ForestViews[views/ - 1 file]
        end
        
        subgraph ElementsModule[Elements Hospitality]
            ElementsRoutes[routes.js]
            ElementsViews[views/ - 1 file]
        end
        
        subgraph BlacktrailsModule[BlackTrails Studio]
            BlacktrailsRoutes[routes.js]
            BlacktrailsViews[views/ - 2 files]
        end
    end
    
    subgraph External[External Services]
        Neon[(Neon PostgreSQL)]
        Anthropic[Anthropic Claude API]
        Resend[Resend Email API]
    end
    
    Server --> BrandDetection
    BrandDetection --> In1Routes
    BrandDetection --> GcoreRoutes
    BrandDetection --> ForestRoutes
    BrandDetection --> ElementsRoutes
    BrandDetection --> BlacktrailsRoutes
    
    In1Routes --> In1Services
    In1Services --> In1Orchestrator
    In1Orchestrator --> In1Alma
    In1Orchestrator --> In1Poeta
    
    In1Routes --> CoreDB
    GcoreRoutes --> CoreEmail
    ElementsRoutes --> CoreDB
    
    CoreDB --> Neon
    In1Alma --> Anthropic
    In1Poeta --> Anthropic
    CoreEmail --> Resend
    
    Server --> CoreMiddleware
    CoreMiddleware --> CoreAuth
    
    style Server fill:#000000,stroke:#ffffff,stroke-width:2px,color:#ffffff
    style CoreLayer fill:#3b82f6,color:#ffffff
    style In1Module fill:#22c55e
    style GcoreModule fill:#f59e0b
    style ForestModule fill:#4a7c23
    style ElementsModule fill:#8b5cf6
    style BlacktrailsModule fill:#ef4444

Architecture Principles

1. Modular Monolith

Single codebase, isolated modules with clear boundaries.

Benefits:

Simpler deployment than microservices
Shared infrastructure efficiency
Clear separation of concerns
Independent feature development

2. Brand Isolation

Each brand is a self-contained module with its own routes, views, and business logic.

Structure:

src/brands/{brand}/
├── routes.js       (Express router)
├── views/          (EJS templates)
└── services/       (Business logic - optional)

No Cross-Brand Dependencies:

IN-1 cannot import from G-CORE
Forest cannot import from Elements
Brands only import from Core

3. Shared Core

Common services used by all brands.

Core Modules:

db.js: PostgreSQL client (Neon)
auth.js: Session & JWT authentication
email.js: Resend email service
middleware.js: Express middleware stack
permissions.js: Role-based authorization

4. Dual Routing

Brands accessible via two methods:

Brand Detection (Query Param):

http://localhost:3000?brand=in1

Direct Mount (Path-based):

http://localhost:3000/in1/rhama

Directory Structure

src/
├── core/                           (6 files - Shared engine)
│   ├── auth.js
│   ├── db.js
│   ├── email.js
│   ├── index.js
│   ├── middleware.js
│   └── permissions.js
│
├── brands/                         (5 isolated modules)
│   ├── in1/
│   │   ├── routes.js
│   │   ├── views/
│   │   │   ├── index.ejs
│   │   │   ├── rhama.ejs
│   │   │   ├── legal.ejs
│   │   │   └── vision.ejs
│   │   └── services/
│   │       ├── almaOrchestrator.js
│   │       ├── almaService.js
│   │       ├── poetService.js
│   │       ├── config/
│   │       │   └── almaConfig.js
│   │       └── prompts/
│   │           ├── alma.js
│   │           └── poeta.js
│   ├── gcore/
│   │   ├── routes.js
│   │   └── views/ (9 files)
│   ├── forest/
│   │   ├── routes.js
│   │   └── views/ (1 file)
│   ├── elements/
│   │   ├── routes.js
│   │   └── views/ (1 file)
│   └── blacktrails/
│       ├── routes.js
│       └── views/ (2 files)
│
└── public/                         (Server + static assets)
    ├── server.js                   (Main entry point)
    ├── routes/
    │   ├── auth.js
    │   └── landing.js
    ├── public/
    │   ├── css/brands/
    │   ├── js/
    │   ├── img/
    │   ├── favicons/
    │   └── content/
    └── utils/
        └── core/

Request Flow

Example: IN-1 Rhama Generation

sequenceDiagram
    participant User
    participant Server
    participant BrandDetection
    participant In1Routes
    participant Orchestrator
    participant AlmaService
    participant PoetaService
    participant Database
    participant AnthropicAPI
    
    User->>Server: POST /in1/api/rhama
    Server->>BrandDetection: Detect brand from path
    BrandDetection->>In1Routes: Route to IN-1 module
    In1Routes->>Orchestrator: processMessage(messages)
    
    Orchestrator->>AlmaService: chatWithAlma(history)
    AlmaService->>AnthropicAPI: Claude Sonnet 4 call
    AnthropicAPI-->>AlmaService: Response with thinking
    AlmaService-->>Orchestrator: {reply, trigger, thinking}
    
    alt Trigger activated
        Orchestrator->>Orchestrator: extractColore(thinking)
        Orchestrator->>PoetaService: generateRhama(color)
        PoetaService->>AnthropicAPI: Claude Sonnet 4 call
        AnthropicAPI-->>PoetaService: Rhama text (5-7-5)
        PoetaService-->>Orchestrator: Rhama poetry
        
        Orchestrator->>Database: INSERT INTO rhamas
        Database-->>Orchestrator: Saved
    end
    
    Orchestrator-->>In1Routes: {reply, rhama}
    In1Routes-->>User: JSON response

Technology Stack

Backend

Runtime: Node.js v20+
Framework: Express.js
Template Engine: EJS
Database: PostgreSQL (Neon serverless)
AI: Anthropic Claude (Sonnet 4)

Frontend

CSS: Vanilla CSS (BEM naming)
JavaScript: Progressive enhancement
Fonts: Inter (UI), Geist (Display)
Icons: Lucide (MIT)

Infrastructure

Hosting: Render.com
Database: Neon (serverless Postgres)
Email: Resend
CDN: Cloudflare (planned)

Development

Version Control: Git
Documentation: Astro + Starlight
Testing: Manual (TDD planned)
Deployment: Git push → auto-deploy

Security

Authentication

Session-based (express-session)
JWT for API tokens
bcrypt password hashing
CSRF protection

Rate Limiting

Global: 100 req/15min
IN-1 Rhama: 30 req/15min
Configurable per endpoint

Data Protection

Environment variables (.env)
Secrets management (Render)
HTTPS only in production
Database SSL connections

Scalability

Current Capacity

Users: 100-1000 concurrent
Database: Shared Neon instance
Server: Single Render instance

Growth Path

Stage 1 (Current): Monolith on single server
Stage 2 (1K-10K users): Horizontal scaling (multiple instances)
Stage 3 (10K+ users): Database read replicas
Stage 4 (50K+ users): Consider microservices extraction

Monitoring & Observability

Logging

Console logs (development)
Structured logs (production - planned)
Error tracking (Sentry - planned)

Metrics

Request counts
Response times
Error rates
Database query performance

Alerts

Server downtime
Database connection failures
API rate limit breaches
Error spike detection

Future Enhancements

Short-term (3 months)

Automated testing suite
CI/CD pipeline
Performance monitoring
Error tracking (Sentry)

Mid-term (6 months)

Mobile apps (React Native)
Websocket real-time features
Background job processing
Advanced analytics

Long-term (12+ months)

Microservices extraction (if needed)
Multi-region deployment
CDN integration
Kubernetes orchestration

“Architecture is the art of knowing what to build, what to buy, and what to ignore.”