Enterprise-Grade AI-Powered Full-Stack Framework
Where Italian Craftsmanship Meets Modern Architecture

---

📋 Table of Contents

• Overview
• Why VELOCE?
• Architecture
• Features
• Quick Start
• NGINX Configuration
• Tech Stack
• Project Structure
• Documentation
• Contributing
• Roadmap
• License
• Additional Resources

---

🎯 Overview

VELOCE is a production-ready, enterprise-grade full-stack framework that represents months of architectural planning and development. This is my first open-source project, born from the vision of creating a comprehensive platform that combines modern best practices with real-world enterprise requirements.

Built with 850+ carefully crafted files across multiple layers, VELOCE is not just another boilerplate—it's a complete ecosystem designed for building scalable SaaS platforms, enterprise applications, and AI-powered services.

🎨 Philosophy

VELOCE embodies Italian craftsmanship in software engineering:

• Veloce means "fast" in Italian—reflecting both performance and development speed
• Quality over quantity: Every file, every pattern, every decision is intentional
• Enterprise-ready: Built for real-world production environments, not just demos
• Developer experience: Comprehensive tooling and documentation for smooth onboarding

---

🚀 Why VELOCE?

The Problem

Building modern enterprise applications requires integrating dozens of technologies, implementing complex patterns, ensuring security, and maintaining scalability. Most frameworks offer pieces of the puzzle—VELOCE delivers the complete picture.

The Solution

VELOCE provides a battle-tested foundation with:

✅ 10 Business Domains - Auth, Billing, Admin, GDPR, Support, Tenant, Analytics, Enrichment, Themes, Meta ✅ 3 Client Platforms - Web, Mobile, and API coverage ✅ AI Integration - Enterprise-grade MCP-powered AI agents ✅ Production Patterns - Real implementations, not TODOs ✅ Security First - OAuth2, GDPR, rate limiting, audit trails ✅ DevOps Ready - Docker, monitoring, health checks, CI/CD ✅ 319 Tests - Comprehensive testing infrastructure (30.54% coverage)

Who Is This For?

• Startup Founders: Launch your MVP faster with enterprise-grade foundations
• Enterprise Teams: Adopt proven patterns and reduce technical debt
• Solo Developers: Learn modern architecture through working examples
• Dev Teams: Standardize your stack with comprehensive conventions
• Students: Study real-world production code and patterns

---

🏗️ Architecture

VELOCE implements Clean Architecture and Domain-Driven Design principles across a sophisticated multi-layer system:

┌─────────────────────────────────────────────────────────────────┐
│                        CLIENT LAYER                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
│  │   Web App    │  │  Mobile App  │  │  Admin Panel │           │
│  │  React 18    │  │   Expo 52    │  │   FastAPI    │           │
│  │  TypeScript  │  │ React Native │  │   Dashboard  │           │
│  └──────────────┘  └──────────────┘  └──────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    API GATEWAY LAYER                            │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  NGINX (Alpine) - Reverse Proxy, Load Balancing, CORS     │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   APPLICATION LAYER                             │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              FASTAPI BACKEND (10 DOMAINS)                │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐          │   │
│  │  │    Auth    │  │  Billing   │  │   GDPR     │          │   │
│  │  │   Domain   │  │   Domain   │  │  Domain    │          │   │
│  │  └────────────┘  └────────────┘  └────────────┘          │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐          │   │
│  │  │  Tenant    │  │ Analytics  │  │  Support   │          │   │
│  │  │   Domain   │  │   Domain   │  │  Domain    │          │   │
│  │  └────────────┘  └────────────┘  └────────────┘          │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐          │   │
│  │  │Enrichment  │  │   Themes   │  │    Meta    │          │   │
│  │  │   Domain   │  │   Domain   │  │   Domain   │          │   │
│  │  └────────────┘  └────────────┘  └────────────┘          │   │
│  │  ┌────────────┐                                          │   │
│  │  │   Admin    │                                          │   │
│  │  │   Domain   │                                          │   │
│  │  └────────────┘                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                   MCP & AUTOMATION LAYER                        │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │       MCP ORCHESTRATION WITH CONDUCTOR (90+ FILES)       │   │
│  │  ┌──────────────────────────────────────────┐            │   │
│  │  │          CONDUCTOR (Strategy Planner)    │            │   │
│  │  │  • Agent Coordinator & Context Manager   │            │   │
│  │  │  • Plan Manager (Tier 1 & 2 workflows)   │            │   │
│  │  └──────────────────────────────────────────┘            │   │
│  │                       ▼                                  │   │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐          │   │
│  │  │ CV Agent   │  │ Debug      │  │ Marketing  │          │   │
│  │  │ (RAG+LLM)  │  │ Agent      │  │ Agents     │          │   │
│  │  └────────────┘  └────────────┘  └────────────┘          │   │
│  │                                                          │   │
│  │  ┌────────────────────────────────────┐                  │   │
│  │  │  Support Agent (Unified LLM)       │                  │   │
│  │  │  • Multi-provider (OpenAI, Claude) │                  │   │
│  │  │  • Task Orchestration Strategies   │                  │   │
│  │  └────────────────────────────────────┘                  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       DATA LAYER                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
│  │ PostgreSQL16 │  │   Redis 7    │  │  ChromaDB    │           │
│  │   Primary    │  │  Cache + Job │  │   Vectors    │           │
│  │   Database   │  │    Queue     │  │   Embeddings │           │
│  └──────────────┘  └──────────────┘  └──────────────┘           │
└─────────────────────────────────────────────────────────────────┘
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                  OBSERVABILITY LAYER                            │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
│  │  Prometheus  │  │  Structlog   │  │Health Checks │           │
│  │   Metrics    │  │   Logging    │  │  Monitoring  │           │
│  └──────────────┘  └──────────────┘  └──────────────┘           │
└─────────────────────────────────────────────────────────────────┘

🎯 Architectural Principles

1. Domain-Driven Design (DDD)

   • 11 bounded contexts with clear responsibilities
   • Rich domain models with business logic
   • Ubiquitous language across teams

2. Clean Architecture

   • Dependency inversion (dependencies point inward)
   • Framework-independent business logic
   • Testable and maintainable code

3. SOLID Principles

   • Single Responsibility across all modules
   • Open/Closed for extensions
   • Interface segregation for flexibility

4. Microservices-Ready

   • Domain isolation enables easy extraction
   • Event-driven communication patterns
   • Independent deployment capability

---

✨ Features

🔐 Authentication & Authorization

Production-grade security implementation:

• ✅ OAuth2 Integration - Google, LinkedIn social login
• ✅ JWT Tokens - Secure token-based authentication with refresh
• ✅ Multi-tenant Architecture - Complete tenant isolation
• ✅ Role-Based Access Control (RBAC) - Granular permissions
• ✅ API Key Management - For external integrations
• ✅ Rate Limiting - Redis-based per-user/IP limiting
• ✅ Session Management - Secure session handling
• ✅ Password Security - Bcrypt hashing, complexity requirements

💳 Billing & Payments

Enterprise payment processing:

• ✅ Stripe Integration - Complete payment lifecycle
• ✅ Webhook Handling - Reliable event processing
• ✅ Subscription Management - Multiple plans and tiers
• ✅ Invoice Generation - Automated billing
• ✅ Payment History - Complete audit trail
• ✅ Refunds & Disputes - Customer support features

🏢 Multi-Tenancy

True SaaS architecture:

• ✅ Tenant Isolation - Complete data separation
• ✅ Subdomain Routing - Custom tenant domains
• ✅ Tenant Configuration - Per-tenant customization
• ✅ Resource Quotas - Usage limits and metering
• ✅ Tenant Analytics - Usage insights per tenant

📊 Analytics & Monitoring

Comprehensive observability:

• ✅ Prometheus Metrics - Application performance monitoring
• ✅ Structured Logging - JSON logs with Structlog
• ✅ Health Checks - Liveness and readiness probes
• ✅ Custom Metrics - Business KPIs tracking
• ✅ Error Tracking - Exception monitoring
• ✅ Audit Logging - Complete action history

🤖 AI & Automation

Powered by MCP (Model Context Protocol) with Conductor:

• ✅ Conductor Framework - Strategic planning with Tier 1 (Fast Track) & Tier 2 (Deep Change) workflows
• ✅ Agent Coordinator - Manages agent lifecycle, context, and handoffs
• ✅ Multi-Agent System - Specialized agents: CV (RAG+LLM), Debug, Support, Marketing
• ✅ Cognitive Memory - ChromaDB-based learning system with vector embeddings
• ✅ Unified LLM Manager - Multi-provider via LiteLLM (OpenAI, Anthropic, extensible)
• ✅ Task Orchestration - Sequential, parallel, priority, and dependency strategies
• ✅ State Management - Agent and conversation state tracking with context awareness
• ✅ Vector Search - Semantic similarity search with ChromaDB for RAG

🎨 Frontend (React 18 + TypeScript)

Modern, performant web application:

• ✅ TypeScript 5.6.3 - Full type safety
• ✅ Vite 6.0+ - Lightning-fast builds
• ✅ TailwindCSS 3.4 - Utility-first styling
• ✅ Radix UI - Accessible component primitives
• ✅ Zustand - Lightweight state management
• ✅ React Query - Server state synchronization
• ✅ React Router 7.8+ - Type-safe routing
• ✅ React Hook Form 7.48+ - Performant form handling
• ✅ Zod - Runtime validation
• ✅ Dark Mode - Theme switching
• ✅ Responsive Design - Mobile-first approach
• ✅ Code Splitting - Optimized bundle sizes
• ✅ PWA Ready - Progressive web app features

📱 Mobile (React Native + Expo)

Cross-platform native experience:

• ✅ Expo 54.0.13+ - Modern development workflow
• ✅ Clean Architecture - Layered mobile architecture
• ✅ Redux Toolkit 1.9.7+ - Predictable state management
• ✅ React Navigation - Native navigation
• ✅ AsyncStorage - Local persistence
• ✅ Offline-First - Sync queue implementation
• ✅ Push Notifications - Firebase Cloud Messaging
• ✅ Biometric Auth - Face ID / Touch ID
• ✅ Camera Integration - Image capture and gallery
• ✅ Deep Linking - Universal links support

🔒 GDPR & Privacy

Complete compliance framework:

• ✅ Data Portability - Export user data
• ✅ Right to be Forgotten - Complete data deletion
• ✅ Consent Management - Cookie and privacy preferences
• ✅ Privacy Policy - Legal documents management
• ✅ Data Processing Agreements - Tenant-level DPAs
• ✅ Audit Trail - Complete data access logs

🎯 Developer Experience

Built for productivity:

• ✅ Docker Compose - One-command setup with infra-net
• ✅ Hot Reload - Instant feedback loop
• ✅ Type Safety - End-to-end type checking
• ✅ API Documentation - Auto-generated Swagger UI
• ✅ Database Migrations - Alembic version control
• ✅ Testing Infrastructure - 319 tests with 30.54% coverage
• ✅ Linting & Formatting - Ruff, ESLint, Prettier
• ✅ UV Package Manager - Fast Python dependency management
• ✅ Docker-based Testing - All tests run in containers

---

🚀 Quick Start

Prerequisites

Ensure you have the following installed:

• Python 3.12+ (Backend)
• Node.js 20+ (Frontend/Mobile)
• Docker & Docker Compose (Recommended)
• Git (Version control)

🐳 Docker Installation (Recommended)

Get started in under 5 minutes:

# 1. Clone the repository
git clone https://github.com/ciroautuori/veloce.git
cd veloce

# 2. Navigate to Docker configuration
cd config/docker

# 3. Choose your setup:

# OPTION A: Local Development (infra-net external network)
docker-compose -f docker-compose.local.yml up -d

# OPTION B: Full Development Stack (isolated network)
docker-compose -f docker-compose-dev.yml up -d

# ✅ Services starting...
# Option A (Local):
# ✓ PostgreSQL 16 → infra-postgres:5432
# ✓ Redis 7 → infra-redis:6379
# ✓ ChromaDB → infra-chroma:8100
# ✓ Backend API → http://localhost:8005
# ✓ Frontend → http://localhost:3000

# Option B (Full Dev):
# ✓ NGINX → http://localhost:8081
# ✓ PostgreSQL 16 → localhost:5435
# ✓ Redis 7 → localhost:6382
# ✓ ChromaDB → http://localhost:8100
# ✓ Backend API → http://localhost:8001
# ✓ Frontend → http://localhost:3000

🔍 Verify Installation

Frontend Application:

http://localhost:3000

Interactive API Documentation (Swagger UI):

# Option A (Local): http://localhost:8005/docs
# Option B (Full Dev): http://localhost:8001/docs

Alternative API Documentation (ReDoc):

# Option A (Local): http://localhost:8005/redoc
# Option B (Full Dev): http://localhost:8001/redoc

NGINX Reverse Proxy (Full Dev only):

# Option B (Full Dev): http://localhost:8081

💻 Manual Installation

Backend Setup

# Navigate to backend
cd apps/backend

# Install dependencies with UV (recommended)
uv pip install -e ".[dev]"

# Or with pip
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Run database migrations
alembic upgrade head

# Start development server (runs on port 8000 internally)
uvicorn app.main:app --reload --port 8000

Frontend Setup

# Navigate to frontend
cd apps/frontend

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start development server
npm run dev

Mobile Setup

# Navigate to mobile
cd apps/mobile

# Install dependencies
npm install

# Start Expo development server
npm start

# Scan QR code with Expo Go app (iOS/Android)

---

🌐 NGINX Configuration

Overview

In the Full Development Stack (docker-compose-dev.yml), NGINX Alpine acts as a reverse proxy and load balancer, providing:

• Reverse Proxying: Routes requests to backend and frontend services
• Load Balancing: Distributes traffic efficiently
• CORS Support: Handles cross-origin requests on /api routes
• Compression: Gzip compression for bandwidth optimization
• Health Checks: Monitors service availability

Architecture

Client Browser (Port 8081)
    ▼
NGINX Alpine (8081:80)
    ├─ /api/* → FastAPI Backend (8000)
    ├─ / → React Frontend (3000)
    ├─ /health → Health check endpoint
    └─ /metrics → Prometheus metrics

Configuration Files

Master Configuration: /config/services/nginx/nginx.conf

• Worker processes: auto (scales with CPU cores)
• Gzip compression: Enabled
• MIME types: Comprehensive file type support
• Logging: Structured access and error logs

Route Configuration: /config/services/nginx/conf.d/default.conf

• Frontend Upstream: server frontend:3000; (Vite dev server)
• Backend Upstream: server backend:8000; (FastAPI app)

Key Routes

Route	Destination	Purpose
/	Frontend (3000)	React SPA application
/api/*	Backend (8000)	API endpoints with CORS
/health	Backend (8000)	Service health check
/metrics	Backend (8000)	Prometheus metrics

CORS Headers

NGINX automatically adds CORS headers on /api routes:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
Access-Control-Allow-Headers: Content-Type, Authorization

Port Mapping

Development Stack (docker-compose-dev.yml):

• NGINX: 8081:80 - Main entry point
• Backend: 8001:8000 - Direct access (bypassing NGINX)
• Frontend: 3000:3000 - Direct access (bypassing NGINX)

Local Stack (docker-compose.local.yml):

• Direct to Backend: 8005:8000 - No NGINX layer
• Direct to Frontend: 3000:3000 - Direct Vite server

Customizing NGINX

To modify NGINX behavior:

1. Edit Master Config:

   vim config/services/nginx/nginx.conf

2. Edit Route Config:

   vim config/services/nginx/conf.d/default.conf

3. Rebuild and Restart:

   docker-compose -f docker-compose-dev.yml down
   docker-compose -f docker-compose-dev.yml up -d

Monitoring NGINX

Check NGINX logs:

# Access logs
docker compose logs -f nginx

# View access in real-time
docker exec veloce-nginx tail -f /var/log/nginx/access.log

---

🛠️ Tech Stack

Backend Stack

Technology	Version	Purpose	Why Chosen
Python	3.12+	Core Language	Modern features, type hints, performance
FastAPI	0.115.6+	Web Framework	Async, automatic docs, validation
SQLAlchemy	2.0.35+	ORM	Mature, powerful, async support
Alembic	1.14.0+	Migrations	Database version control
PostgreSQL	16	Database	ACID, JSON support, reliability
Redis	5.2.1+	Cache & Queue	Caching, sessions, rate limiting
Pydantic	2.10.4+	Validation	Runtime validation, settings management
Pytest	8.3.4+	Testing	Async support, comprehensive fixtures
Structlog	24.4.0+	Logging	Structured JSON logging, Sentry support
Uvicorn	0.34.0+	ASGI Server	High performance, auto-reload

Frontend Stack

Technology	Version	Purpose	Why Chosen
React	18.3.1+	UI Framework	Virtual DOM, concurrent rendering
TypeScript	5.6.3+	Type Safety	Catch errors early, better IDE support
Vite	6.0.5+	Build Tool	Fast HMR, optimized builds
TailwindCSS	3.4.17+	Styling	Utility-first, rapid development
Radix UI	Latest	Components	Accessible, unstyled, composable
Zustand	4.4.7+	State Management	Simple, performant, no boilerplate
React Query	5.17.0+	Server State	TanStack Query, caching, sync
React Router	7.8.2+	Routing	Data-driven routing with loaders
React Hook Form	7.48.2+	Forms	Performant, minimal re-renders
Zod	3.22.4+	Schema Validation	TypeScript-first, runtime validation

Mobile Stack

Technology	Version	Purpose	Why Chosen
React Native	0.72.6+	Mobile Framework	Cross-platform, native performance
Expo	54.0.13+	Development Platform	Dev client, OTA updates, EAS
Redux Toolkit	1.9.7+	State Management	Predictable, DevTools, middleware
React Navigation	Latest	Navigation	Native transitions, deep linking
AsyncStorage	1.19.5+	Local Storage	Simple API, reliable

AI & ML Stack

Technology	Version	Purpose	Why Chosen
MCP + Conductor	Latest	Agent System	Model Context Protocol with strategic planning
LiteLLM	1.0.0+	LLM Manager	Multi-provider support (OpenAI, Anthropic)
ChromaDB	0.5.23+	Vector DB	Embeddings, semantic search, cognitive memory
OpenAI API	1.58.1+	LLM Provider	State-of-the-art GPT models
Anthropic Claude	0.18.0+	LLM Provider	Advanced reasoning and analysis
LangChain	0.3.14+	RAG Framework	Document Q&A, chains, semantic search
SentenceTransformers	2.2.0+	Embeddings	Fast embeddings, semantic similarity
Unstructured	0.16.22+	Document Parsing	PDF, DOCX extraction, document intelligence

DevOps Stack

Technology	Version	Purpose	Why Chosen
Docker	24+	Containerization	Industry standard, reproducible
Docker Compose	v2+	Orchestration	Easy multi-container setup
NGINX	Alpine	Reverse Proxy	Lightweight, efficient, SSL support
Prometheus	Latest	Metrics	Standard for monitoring
GitHub Actions	-	CI/CD	Integrated, free for public repos

---

📁 Project Structure

veloce/
├── apps/
│   ├── backend/                    # FastAPI Backend (395 files)
│   │   ├── app/
│   │   │   ├── core/              # Core utilities and config
│   │   │   │   ├── config.py      # Configuration management
│   │   │   │   ├── security.py    # Security utilities
│   │   │   │   ├── database.py    # Database connection
│   │   │   │   └── mcp/           # MCP orchestration system
│   │   │   │       ├── conductor/    # Conductor (strategic planner)
│   │   │   │       │   ├── agent_coordinator.py
│   │   │   │       │   ├── context_manager.py
│   │   │   │       │   └── plan_manager.py
│   │   │   │       ├── agents/    # AI agents (Debug, Support, Marketing, CV)
│   │   │   │       ├── llm/       # Unified LLM manager
│   │   │   │       ├── memory/    # Cognitive memory system
│   │   │   │       ├── state/     # State management
│   │   │   │       ├── task/      # Task orchestration
│   │   │   │       └── orchestrator.py
│   │   │   ├── domain/            # 10 Business Domains
│   │   │   │   ├── auth/          # Authentication & Authorization
│   │   │   │   ├── billing/       # Payments & Subscriptions
│   │   │   │   ├── admin/         # Admin management
│   │   │   │   ├── gdpr/          # GDPR compliance
│   │   │   │   ├── support/       # Customer support
│   │   │   │   ├── tenant/        # Multi-tenancy
│   │   │   │   ├── analytics/     # Analytics & metrics
│   │   │   │   ├── enrichment/    # Data enrichment
│   │   │   │   ├── themes/        # Theming system
│   │   │   │   └── meta/          # Metadata management
│   │   │   ├── infrastructure/    # Infrastructure layer
│   │   │   │   ├── monitoring/    # Monitoring & metrics
│   │   │   │   ├── database/      # Database utilities
│   │   │   │   └── external/      # External integrations
│   │   │   ├── middleware/        # Custom middleware
│   │   │   ├── models/            # SQLAlchemy models
│   │   │   ├── schemas/           # Pydantic schemas
│   │   │   ├── services/          # Business logic
│   │   │   ├── repositories/      # Data access layer
│   │   │   └── api/               # API routes
│   │   ├── tests/                 # Comprehensive tests (319 tests, 30.54% coverage)
│   │   ├── alembic/               # Database migrations
│   │   ├── pyproject.toml         # UV package configuration
│   │   ├── uv.lock                # UV lock file
│   │   └── main.py                # Application entry point
│   │
│   ├── frontend/                   # React Frontend (200+ files)
│   │   ├── src/
│   │   │   ├── components/        # Reusable UI components
│   │   │   │   ├── ui/            # Base UI components (Radix)
│   │   │   │   ├── forms/         # Form components
│   │   │   │   ├── layouts/       # Layout components
│   │   │   │   └── features/      # Feature-specific components
│   │   │   ├── pages/             # Page components
│   │   │   ├── hooks/             # Custom React hooks
│   │   │   ├── services/          # API service layer
│   │   │   ├── stores/            # Zustand stores
│   │   │   ├── utils/             # Utility functions
│   │   │   ├── types/             # TypeScript types
│   │   │   ├── styles/            # Global styles
│   │   │   └── config/            # Configuration
│   │   ├── public/                # Static assets
│   │   ├── package.json           # Dependencies
│   │   ├── pnpm-lock.yaml         # PNPM lock file
│   │   ├── tsconfig.json          # TypeScript config
│   │   ├── vite.config.ts         # Vite configuration
│   │   └── tailwind.config.js     # Tailwind configuration
│   │
│   ├── mobile/                     # React Native Mobile (200+ files)
│   │   ├── src/
│   │   │   ├── core/              # Core layer (DI, config)
│   │   │   ├── data/              # Data layer (API, storage)
│   │   │   ├── domain/            # Domain layer (entities, use cases)
│   │   │   ├── presentation/      # Presentation layer (UI)
│   │   │   │   ├── components/    # Reusable components
│   │   │   │   ├── screens/       # Screen components
│   │   │   │   ├── navigation/    # Navigation configuration
│   │   │   │   └── redux/         # Redux store
│   │   │   └── utils/             # Utility functions
│   │   ├── assets/                # Images, fonts
│   │   ├── app.json               # Expo configuration
│   │   ├── package.json           # Dependencies
│   │   └── tsconfig.json          # TypeScript config
│   │
├── config/                         # Configuration files
│   ├── docker/                    # Docker configurations
│   │   ├── docker-compose.local.yml    # Local development
│   │   ├── docker-compose-dev.yml     # Development environment
│   │   ├── docker-compose-prod.yml    # Production environment
│   │   ├── dockerfiles/                # Dockerfiles
│   │   │   ├── backend.Dockerfile
│   │   │   └── frontend.Dockerfile
│   │   └── README.md                 # Docker documentation
│   ├── env/                       # Environment templates
│   │   ├── .env.backend.example   # Backend env template
│   │   ├── .env.frontend.example  # Frontend env template
│   │   └── .env.mobile.example    # Mobile env template
│   └── services/                  # Service configurations
│       ├── nginx/                 # Nginx configuration
│       │   ├── nginx.conf
│       │   └── conf.d/
│       └── prometheus.yml         # Prometheus configuration
│
├── docs/                           # Comprehensive documentation
│   ├── PORTS.md                   # Port allocation registry
│   ├── DOCUMENTATION.md           # Main technical documentation
│   ├── architecture/              # Architecture diagrams & docs
│   │   ├── backend-architecture.md
│   │   ├── frontend-architecture.md
│   │   ├── mobile-architecture.md
│   │   └── ai-architecture.md
│   ├── guides/                    # How-to guides
│   │   ├── deployment.md          # Deployment guide
│   │   ├── development.md         # Development workflow
│   │   ├── testing.md             # Testing guide
│   │   └── troubleshooting.md     # Common issues
│   └── api/                       # API documentation
│       └── endpoints.md           # Endpoint reference
│
├── scripts/                        # Utility scripts
│   ├── setup.sh                   # Initial setup
│   ├── test.sh                    # Run all tests
│   └── deploy.sh                  # Deployment script
│
├── .github/                        # GitHub configuration
│   ├── workflows/                 # CI/CD workflows
│   │   ├── backend-ci.yml         # Backend CI
│   │   ├── frontend-ci.yml        # Frontend CI
│   │   └── mobile-ci.yml          # Mobile CI
│   ├── ISSUE_TEMPLATE/            # Issue templates
│   └── PULL_REQUEST_TEMPLATE.md   # PR template
│
├── CONTRIBUTING.md                 # Contribution guidelines
├── CODE_OF_CONDUCT.md             # Code of conduct
├── CHANGELOG.md                   # Version history
├── BRAND.md                       # Brand guidelines
├── LICENSE                        # MIT License
└── README.md                      # This file

📊 Project Statistics

• Total Files: 850+
• Lines of Code: ~50,000+
• Backend Files: 300+
• Frontend Files: 200+
• Mobile Files: 200+
• MCP System Files: 90+ (including Conductor framework)
• Business Domains: 10 core domains
• Test Files: 39 test files
• Total Tests: 319
• Test Coverage: 30.54%
• Documentation Pages: 20+

---

📚 Documentation

Core Documentation

• 📖 Complete Documentation - Comprehensive technical guide
• 🏗️ Architecture Guide - System design and patterns
• 🚀 Development Guide - Local development workflow
• 🧪 Testing Guide - Testing strategies and examples
• 🚢 Deployment Guide - Production deployment
• 🐛 Troubleshooting - Common issues and solutions

Docker & DevOps

• 🐳 Docker Guide - Container setup and orchestration
• 📊 Monitoring Setup - Prometheus and logging
• 🔄 CI/CD Pipeline - Continuous integration and deployment

Domain Documentation

Each domain has comprehensive documentation:

• 🔐 Auth Domain - Authentication and authorization
• 💳 Billing Domain - Payment processing and subscriptions
• 👥 Tenant Domain - Multi-tenancy implementation
• 📊 Analytics Domain - Metrics and reporting
• 🎨 Themes Domain - Customization system
• 🛡️ GDPR Domain - Privacy compliance
• 💬 Support Domain - Customer support features
• 🔧 Admin Domain - Administrative tools
• ⚡ Enrichment Domain - Data enrichment
• 📝 Meta Domain - Metadata management

API Documentation

When running locally, access interactive documentation:

• Swagger UI: http://localhost:8005/docs
• ReDoc: http://localhost:8005/redoc
• OpenAPI Schema: http://localhost:8005/openapi.json

Brand & Style

• 🎨 Brand Guidelines - Logo, colors, typography, usage rules
• 📐 Design System - UI components and patterns

---

🤝 Contributing

VELOCE is my first open-source project, and contributions are warmly welcomed! Whether you're fixing bugs, adding features, improving documentation, or sharing ideas, your help makes VELOCE better for everyone.

🌟 Ways to Contribute

1. Code Contributions

• 🐛 Fix bugs or issues
• ✨ Implement new features
• ⚡ Improve performance
• 🔒 Enhance security

2. Documentation

• 📝 Improve existing docs
• 📚 Write tutorials and guides
• 🌍 Translate documentation
• 💡 Add examples and use cases

3. Community

• 💬 Answer questions in Discussions
• 🎓 Share your VELOCE projects
• 📢 Write blog posts or articles
• 🎤 Give talks at meetups

4. Testing & Feedback

• 🧪 Write tests
• 🐛 Report bugs
• 💡 Suggest features
• 📊 Share usage metrics

🚀 Getting Started

1. Read the Contributing Guide - Essential information for contributors
2. Check Good First Issues - Perfect for newcomers
3. Join Discussions - Ask questions, share ideas
4. Review the Code of Conduct - Community guidelines

📋 Contribution Process

# 1. Fork the repository
# Click "Fork" button on GitHub

# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/veloce.git
cd veloce

# 3. Create a feature branch
git checkout -b feature/amazing-feature

# 4. Make your changes
# Edit files, add features, fix bugs

# 5. Test your changes
cd apps/backend && pytest
cd apps/frontend && npm test

# 6. Commit with clear message
git commit -m "feat: add amazing feature"

# 7. Push to your fork
git push origin feature/amazing-feature

# 8. Open a Pull Request
# Go to GitHub and create a PR from your fork

📝 Commit Convention

We follow Conventional Commits:

feat: add new authentication provider
fix: resolve user registration bug
docs: update installation guide
style: format code with black
refactor: restructure billing domain
test: add tests for payment flow
chore: update dependencies

🎯 Areas Needing Help

Current priorities for contributions:

• Testing: Increase coverage to 80%+
• Documentation: More tutorials and examples
• Internationalization: Add i18n support
• Mobile Features: Enhanced offline capabilities
• AI Agents: Additional specialized agents
• Performance: Optimize database queries
• Security: Security audit and improvements
• DevOps: Kubernetes configurations
• Examples: Real-world implementation examples
• Integrations: Additional third-party services

💡 Feature Requests

Have an idea? We'd love to hear it!

1. Check existing issues to avoid duplicates
2. Open a feature request
3. Describe the problem and proposed solution
4. Add mockups or examples if applicable

🐛 Bug Reports

Found a bug? Help us fix it!

1. Check if it's already reported
2. Open a bug report
3. Include reproduction steps
4. Add environment details (OS, versions, etc.)
5. Attach logs or screenshots if relevant

---

🗺️ Roadmap

✅ Version 2.0 (Released - 2026-01-10)

Goal: Enterprise-grade AI-powered framework with MCP and Conductor

• Core architecture with 10 business domains
• Authentication and authorization
• Multi-tenancy support
• Payment processing (Stripe)
• MCP (Model Context Protocol) System - Enterprise AI agents orchestration with Conductor
• Conductor Framework - Strategic planning engine for Tier 1/2 workflows
• Cognitive memory with ChromaDB
• Multi-provider LLM support via LiteLLM (OpenAI, Anthropic)
• Specialized agents (Debug, Support, Marketing, CV)
• Mobile app (iOS/Android)
• Docker deployment with UV package manager
• 319 comprehensive tests (30.54% coverage)
• Enhanced monitoring system (Prometheus metrics)
• Comprehensive documentation

🚀 Version 2.1 (Q1 2026)

Focus: Enhanced developer experience and testing

• Kubernetes Support - K8s manifests and Helm charts
• GraphQL API - Alternative to REST
• WebSockets - Real-time features
• Increase test coverage to 60%+
• Advanced Monitoring - Grafana dashboards
• E2E Testing - Playwright tests
• Storybook - Component documentation
• CLI Tool - Project scaffolding

🌟 Version 3.0 (Q2 2026)

Focus: Enterprise scaling and AI enhancements

• SSO Integration - SAML, OIDC support
• Advanced RBAC - Attribute-based access control
• Workflow Engine - Custom business workflows
• Advanced Analytics - ML-powered insights
• Notification System - Email, SMS, push, webhooks
• File Management - Document storage and processing
• API Gateway - Kong or Tyk integration
• Message Queue - RabbitMQ or Kafka
• Enhanced AI Agents - More specialized agents
• Reach 80%+ test coverage

💎 Future Vision (2026+)

Focus: Innovation and ecosystem

• Marketplace - Plugin and theme marketplace
• Low-Code Builder - Visual application builder
• Multi-Cloud Support - AWS, Azure, GCP deployment
• Edge Computing - CDN and edge functions
• Blockchain Integration - Web3 features
• AR/VR Support - Immersive experiences
• Voice Interface - Voice-controlled features
• VELOCE Cloud - Managed hosting platform

📊 Metrics & Goals

By End of 2026:

• ⭐ 1,000+ GitHub Stars
• 🤝 100+ Contributors
• 📦 10,000+ Downloads
• 🏢 50+ Production Deployments
• 📝 100+ Documentation Pages
• 🧪 80%+ Test Coverage (target)
• 🌍 Support for 10+ Languages
• 🎓 5,000+ Developer Community

---

🌍 Community

Join the VELOCE community and connect with other developers!

💬 Where to Find Us

• GitHub Discussions: Ask questions, share ideas
• Issues: Report bugs, request features
• Pull Requests: Contribute code
• Changelog: Stay updated

📧 Contact

• Email: ciroautuori@example.com
• Website: [Coming Soon]
• Blog: [Coming Soon]

🎓 Learning Resources

For Beginners

• 📚 Start with Quick Start
• 🎯 Try Good First Issues
• 📖 Read Development Guide

For Advanced Users

• 🏗️ Study Architecture Guide
• 🔧 Explore Domain Documentation
• 🧪 Review Testing Strategies

Video Tutorials

• 🎥 Getting Started with VELOCE (Coming Soon)
• 🎥 Building Your First Feature (Coming Soon)
• 🎥 Deploying to Production (Coming Soon)

🏆 Recognition

Special thanks to early contributors and supporters:

• Contributors will be listed here
• Star the project to show your support! ⭐

---

🎖️ Acknowledgments

🇮🇹 Made in Italy

VELOCE is proudly Made in Italy, embodying the values of Italian craftsmanship:

• Velocità (Speed): Performance-first architecture
• Qualità (Quality): Meticulous attention to detail
• Bellezza (Beauty): Elegant, clean code
• Passione (Passion): Built with love and dedication

Like Ferrari brings Italian excellence to automotive, and Armani to fashion, VELOCE brings these values to software engineering.

🤖 Powered by DataPizza AI

Special thanks to DataPizza Labs for their incredible DataPizza AI system:

• Enterprise-grade AI agents framework
• Developed by talented Italian engineers
• Powers VELOCE's intelligent automation
• Open-source and community-driven

DataPizza AI provides:

• Multi-agent orchestration
• RAG (Retrieval-Augmented Generation)
• Multi-provider LLM support
• Production-ready implementations

Visit DataPizza AI on GitHub to learn more.

🙏 Technology Acknowledgments

VELOCE builds upon the shoulders of giants. Thank you to:

• FastAPI - Sebastián Ramírez for the incredible web framework
• React - Meta and the React team for revolutionary UI library
• Python - Guido van Rossum and the Python community
• PostgreSQL - The PostgreSQL Global Development Group
• Redis - Salvatore Sanfilippo and Redis Labs
• Docker - Docker Inc. for containerization
• TypeScript - Microsoft for type safety in JavaScript
• Expo - Expo team for amazing React Native DX

And countless other open-source projects that make VELOCE possible.

📚 Inspiration

VELOCE was inspired by studying and learning from:

• Django - Python web framework excellence
• Ruby on Rails - Convention over configuration
• Spring Boot - Enterprise Java patterns
• NestJS - Modern Node.js architecture
• Laravel - Elegant PHP development

🎓 My Journey

This is my first open-source project, born from:

• Months of planning - Careful architectural decisions
• Real-world experience - Production lessons learned
• Passion for quality - No compromises on code quality
• Community first - Built to share and help others
• Continuous learning - Growing with each contribution

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

What This Means

✅ You Can:

• Use commercially
• Modify and distribute
• Use privately
• Sublicense

❌ You Must:

• Include copyright notice
• Include license text

❌ No Warranty:

• Software provided "as is"
• No liability for damages

Attribution

If you use VELOCE in your project, we'd appreciate attribution:

Built with [VELOCE](https://github.com/ciroautuori/veloce) -
Enterprise-Grade Full-Stack Framework

---

🔒 Security

Security is a top priority for VELOCE.

Reporting Vulnerabilities

If you discover a security vulnerability, please:

1. DO NOT open a public issue
2. Email: security@veloce.dev
3. Include:
   • Description of the vulnerability
   • Steps to reproduce
   • Potential impact
   • Suggested fix (if any)

We will:

• Acknowledge receipt within 24 hours
• Provide a detailed response within 72 hours
• Work on a fix immediately
• Credit you in the security advisory (if desired)

Security Features

VELOCE includes enterprise-grade security:

• 🔐 OAuth2 + JWT authentication
• 🛡️ SQL injection prevention (SQLAlchemy)
• 🔒 XSS protection (React, CSP headers)
• 🚫 CSRF protection
• ⏱️ Rate limiting per user/IP
• 📝 Audit logging
• 🔑 API key management
• 🌐 HTTPS/TLS support
• 🛂 CORS configuration
• 📋 GDPR compliance tools

Best Practices

When deploying VELOCE:

1. Always use HTTPS in production
2. Keep dependencies updated regularly
3. Use strong secrets for JWT and API keys
4. Enable rate limiting to prevent abuse
5. Monitor logs for suspicious activity
6. Regular security audits recommended
7. Backup database regularly
8. Use environment variables for sensitive data

---

📈 Project Status

Current Status: v2.0.0 Released 🚀

VELOCE has reached v2.0.0 with the new MCP (Model Context Protocol) system and enhanced testing infrastructure.

Stats

• Started: 2024
• Current Version: 2.0.0 (Stable)
• Contributors: Growing community
• Production Ready: 95%
• Test Coverage: 30.54% (target: 80%+)
• Total Tests: 319
• Documentation: Comprehensive

Stability

Component	Status	Production Ready
Backend API	✅ Stable	Yes
Frontend Web	✅ Stable	Yes
Mobile App	✅ Stable	Yes
MCP AI System	✅ Stable	Yes
Docker Setup	✅ Stable	Yes
Documentation	✅ Complete	Yes
Testing	🔄 Growing	30.54% coverage

Release Cycle

• Major versions: Every 6-12 months
• Minor versions: Every 2-3 months
• Patch versions: As needed
• Security patches: Immediate

---

🎯 Use Cases

VELOCE is perfect for:

🚀 SaaS Platforms

Build multi-tenant SaaS applications with:

• User management and authentication
• Subscription billing (Stripe)
• Usage analytics and metrics
• Custom theming per tenant
• GDPR compliance built-in

🏢 Enterprise Applications

Enterprise-ready with:

• Domain-driven architecture
• Microservices patterns
• Security and compliance
• Audit logging
• Role-based access control

🤖 AI-Powered Services

Leverage AI capabilities:

• RAG-based chatbots
• Document analysis
• Marketing automation
• Smart recommendations
• Custom AI agents

📱 Mobile-First Products

Cross-platform mobile apps:

• Native iOS and Android
• Offline-first architecture
• Push notifications
• Biometric authentication

🎓 Learning Projects

Perfect for education:

• Study modern architecture
• Learn best practices
• Real-world patterns
• Production-ready code

---

🔗 Related Projects

Official Repositories

• VELOCE Main: github.com/ciroautuori/veloce
• DataPizza AI: github.com/datapizza-labs/datapizza-ai

Example Projects

• Coming Soon: Example applications built with VELOCE
• Coming Soon: Starter templates
• Coming Soon: Integration examples

---

💻 System Requirements

Development

Minimum:

• CPU: 4 cores
• RAM: 8 GB
• Disk: 20 GB free space
• OS: Windows 10+, macOS 11+, Linux (Ubuntu 20.04+)

Recommended:

• CPU: 8+ cores
• RAM: 16+ GB
• Disk: 50+ GB SSD
• OS: Latest versions

Production

Small Deployment (< 1000 users):

• CPU: 2 cores
• RAM: 4 GB
• Disk: 20 GB
• Database: PostgreSQL 16
• Cache: Redis 7

Medium Deployment (1000-10000 users):

• CPU: 4 cores
• RAM: 8 GB
• Disk: 50 GB
• Load balancer: Required
• Database: PostgreSQL 16 (replicated)

Large Deployment (10000+ users):

• CPU: 8+ cores
• RAM: 16+ GB
• Disk: 100+ GB
• Kubernetes: Recommended
• Database: PostgreSQL cluster
• CDN: Required

---

📚 Additional Resources

Official Documentation

• ABOUT.md - Project vision, creator background, and philosophy
• CONTRIBUTING.md - How to contribute to VELOCE
• CODE_OF_CONDUCT.md - Community guidelines and standards
• SECURITY.md - Security policy and vulnerability reporting
• CHANGELOG.md - Release history and features
• LICENSE - MIT License details

Developer Tools

Development Commands - All available via make:

make help              # Show all available commands
make dev              # Start full development stack
make test             # Run all tests
make lint             # Lint code
make format           # Format code
make security-check   # Run security audits

VS Code Integration:

• .vscode/settings.json - Recommended project settings
• .vscode/extensions.json - Suggested VS Code extensions
• .vscode/launch.json - Debug configurations for backend, frontend, tests

CI/CD Pipelines:

• .github/workflows/ci.yml - Automated testing and quality checks
• .github/workflows/deploy.yml - Docker image building and publishing

Code Formatting:

• .editorconfig - Consistent formatting across editors
• Makefile - Development and deployment automation

Learning Resources

Getting Started

1. Read ABOUT.md - Understand the project vision
2. Follow Quick Start - Get VELOCE running locally
3. Explore Project Structure - Understand the codebase
4. Read Architecture - Learn the design patterns

Advanced Topics

• Study the backend code in apps/backend/app/core/ - DDD and Clean Architecture
• Explore MCP system in apps/backend/app/core/mcp/ - AI agents orchestration
• Review test suite in apps/backend/tests/ - Testing best practices

External Resources

• OWASP Security Guidelines
• FastAPI Documentation
• React Documentation
• PostgreSQL Documentation

Community & Support

Channel	Link
Discussions	GitHub Discussions
Issue Tracker	GitHub Issues
Security	SECURITY.md
Email	ciroautuori@example.com

---

❓ FAQ

General Questions

Q: Is VELOCE production-ready? A: Yes! VELOCE v2.0.0 is production-ready with 850+ files and used in real applications. Currently at 95% production readiness with comprehensive MCP system, 319 tests, and enterprise-grade features.

Q: Can I use this for commercial projects? A: Absolutely! VELOCE is MIT licensed, perfect for commercial use.

Q: Do I need to know Python and React? A: Basic knowledge is recommended, but VELOCE's documentation helps you learn.

Q: Is VELOCE suitable for beginners? A: Yes! Start with the Quick Start guide and explore gradually.

Technical Questions

Q: Why FastAPI instead of Django? A: FastAPI offers async support, automatic docs, better performance, and modern Python features.

Q: Can I use a different database? A: PostgreSQL is recommended, but SQLAlchemy supports MySQL, SQLite, and others.

Q: Does it support microservices? A: Yes! Domains are designed to be extracted into microservices easily.

Q: What about scaling? A: VELOCE is designed to scale horizontally with Docker/Kubernetes.

Deployment Questions

Q: Can I deploy on AWS/Azure/GCP? A: Yes! Docker containers work on any cloud platform.

Q: Do you provide hosting? A: Not yet, but VELOCE Cloud is on the roadmap.

Q: What's the deployment process? A: See Deployment Guide for detailed instructions.

---

🎊 Thank You!

Thank you for checking out VELOCE! This project represents months of work, learning, and passion for building quality software.

Whether you:

• ⭐ Star the repository
• 🐛 Report a bug
• 💡 Suggest a feature
• 🤝 Contribute code
• 📢 Share with others
• 📚 Improve documentation

Every contribution matters and helps make VELOCE better!

---

VELOCE
Where Italian Speed Meets AI Intelligence
🏎️ 🇮🇹 🤖

Built with ❤️ and ☕ in Italy

⭐ Star us on GitHub • 🐛 Report Bug • 💬 Discussions

_{Made with passion by Ciro Autuori}