AI Development Guide - Structum Lab

Guide completa per sviluppo AI-assisted (Agent & Chat-based)

📋 Indice

  1. Project Charter

  2. AI Primer - Context Essenziale

  3. Guida per AI Agent (Agentic)

  4. Guida per AI Chat-based

  5. Workflow Operativi

  6. Quality Gates

🎯 Project Charter

Vision

Structum è l’infrastruttura invisibile per applicazioni Python production-ready.

Non è un framework web/CLI/ORM. È il layer fondazionale che gestisce:

  • Configuration management

  • Logging & Observability

  • Database connections

  • Authentication & Authorization

  • Caching & Storage

  • Message queues & Background jobs

  • CLI tooling

Mission

Agnostic, Modular, Production-Ready

  1. Agnostic by Design: Solo Protocol interfaces, nessun lock-in

  2. Modulare: Core minimalista + plugin opzionali

  3. Production-Ready: Ogni feature è enterprise-grade dall’inizio

Architettura

packages/
├── core/src/structum_lab/          # Framework core (Protocols + base)
├── dynaconf/src/structum_lab/      # Configuration plugin
├── observability/src/structum_lab/ # Logging & metrics plugin
├── auth/src/structum_lab/          # Authentication (in development)
├── database/src/structum_lab/      # Database interfaces (in development)
├── di/src/structum_lab/            # Dependency Injection
└── bootstrap/src/structum_lab/     # Bootstrap & initialization

Principio fondamentale: Il core contiene SOLO Protocol interfaces. Nessuna logica.

Plugin Roadmap

Priorità:

  1. structum_database (Critical) - Connection pooling + ORM-agnostic

  2. structum_auth (Critical) - JWT + OAuth2 + RBAC

  3. structum_cli (High, Core) - Typer + Rich CLI infrastructure

  4. structum_storage (High) - S3/Local/Azure abstraction

  5. structum_messaging (High) - Redis Streams/RabbitMQ/Kafka

  6. structum_cache (High) - Redis/Memcached

  7. structum_jobs (Medium) - Celery background workers

  8. structum_testing (Low) - Fixtures + mocks per tutti i plugin

🤖 AI Primer - Context Essenziale

Cosa Deve Sapere un AI

1. Filosofia del Progetto

Vibe Coding Ready: Il progetto è progettato per AI development.

  • ROADMAP dettagliata (~2200 righe) con esempi completi

  • Ogni plugin ha spec complete con codice runnable

  • Pattern standardizzati e ripetibili

  • Anti-pattern documentati

2. Struttura Repository

structum-lab/
├── packages/                             # Monorepo packages
│   ├── core/src/structum_lab/           # Core interfaces & base
│   ├── dynaconf/src/structum_lab/       # Config (COMPLETE)
│   ├── observability/src/structum_lab/  # Logs+Metrics (COMPLETE)
│   ├── auth/src/structum_lab/           # Authentication (WIP)
│   ├── database/src/structum_lab/       # Database (WIP)
│   ├── di/src/structum_lab/             # Dependency Injection (COMPLETE)
│   └── bootstrap/src/structum_lab/      # Bootstrap (COMPLETE)
├── demo/                                 # Demo suite
│   ├── 01-logging-basics/               # Logging fundamentals
│   ├── 02-observability-full/           # Metrics + context
│   ├── 03-zero-config/                  # Auto-discovery
│   ├── 04-web-integration/              # FastAPI integration
│   ├── 05-standalone-plugins/           # Plugins without DI
│   ├── 10-di-fastapi/                   # DI with FastAPI
│   └── archive/                         # Legacy demos
├── docs/                                 # MkDocs documentation
├── ROADMAP.md                            # Plugin development guide
└── pyproject.toml                        # Root monorepo config

3. Detailed explanation of core modules architecture

1. Agnostic by Design

# Core: Solo l'interfaccia
class DatabaseInterface(Protocol):
    def get_connection(self) -> Connection: ...
    def transaction(self) -> ContextManager: ...

# Plugin: Implementazione concreta (SQLAlchemy, psycopg, etc.)
class SQLAlchemyDatabase(DatabaseInterface):
    # Implementazione specifica

Principio: L’applicazione dipende dall’interfaccia, non dall’implementazione.
→ Permette di cambiare backend senza riscrivere codice.

2. Modulare & Stratificato

Architettura a 3 layer:

┌─────────────────────────────────────┐
│  Application (demo)        │  ← Usa le interfaces
├─────────────────────────────────────┤
│  Plugins (dynaconf, observability)  │  ← Implementazioni concrete
├─────────────────────────────────────┤
│  Core (structum_lab)                │  ← Solo Protocols
└─────────────────────────────────────┘

Principio: Il core è minimalista, i plugin sono opzionali.
→ Installi solo ciò che ti serve.

Core Modules Clarification

Important: Il core ha 3 moduli built-in:

packages/core/src/structum_lab/
├── config/          # ConfigInterface protocol
├── logging/         # LoggerInterface protocol  
├── monitoring/      # MetricsInterface protocol
├── auth/            # AuthInterface protocol
├── database/        # DatabaseInterface protocol
└── plugins/         # Plugin system base

Il core contiene principalmente interfaces (Protocols)!

Le implementazioni sono in package separati:

packages/
├── dynaconf/src/structum_lab/
│   └── DynaconfConfigProvider implements ConfigInterface
└── observability/src/structum_lab/
    ├── StructuredLogger implements LoggerInterface
    └── PrometheusMetrics implements MetricsInterface

Pattern:

Core Module          →  Package Implementation
--------------          ----------------------
config/              →  packages/dynaconf/
logging/             →  packages/observability/ (logging part)
monitoring/          →  packages/observability/ (Prometheus part)
auth/                →  packages/auth/
database/            →  packages/database/

Why bundle logging + monitoring in one plugin?

  • “Observability” is a unified concept

  • Same backend often provides both (Datadog, Prometheus+Loki)

  • Reduces plugin proliferation

  • Industry standard pattern

Why these 3 modules in core?

  • config: Needed by ALL plugins (get_config())

  • logging: Needed for debugging (get_logger())

  • monitoring: Needed for production observability (get_metrics())

All 3 have NoOp fallbacks, so core has zero external dependencies!

3. Plugin Development Pattern

SEMPRE seguire questo ordine:

# 1. Core Interface (Protocol)
# packages/core/src/structum_lab/database/interfaces.py
class DatabaseInterface(Protocol):
    def get_connection(self) -> Connection: ...
    def transaction(self) -> ContextManager: ...
    def health_check(self) -> Dict[str, Any]: ...

# 2. Plugin Implementation
# packages/database/src/structum_lab/sqlalchemy.py
class SQLAlchemyDatabase(DatabaseInterface):
    # Implementazione concreta
    
    def __init__(self):
        cfg = get_config()  # SEMPRE da config
        self._metrics = get_metrics("structum.database")  # SEMPRE emit metrics
        self._log = get_logger(__name__)  # SEMPRE structured logging

Checklist Obbligatorio per ogni plugin:

  • ✅ Protocol nel core

  • ✅ Config-driven (no hardcoded)

  • ✅ Metrics emission

  • ✅ Structured logging

  • ✅ Health checks

  • ✅ Graceful shutdown

  • ✅ Documentation

  • ✅ Tests

4. Code Style & Standards

Type Hints: 100% coverage, mypy strict mode

from typing import Protocol, Dict, Any, Optional

def get_config(profile: Optional[str] = None) -> Dict[str, Any]:
    ...

Naming Conventions:

  • Interfaces: XyzInterface (Protocol)

  • Implementations: ConcreteXyz (es. SQLAlchemyDatabase)

  • Plugin prefix: structum_ (es. structum_database)

Imports: Core mai dipende da plugin

# ✅ CORRETTO (plugin importa core)
from structum_lab.config import get_config

# ❌ SBAGLIATO (core importa plugin)
from structum_database import SQLAlchemy  # NO!

5. Documentation Requirements

Per ogni plugin:

  • README.md - Quick start

  • docs/ - Detailed guides

  • Esempi in demo/

  • Entry in main ROADMAP.md

🤖 Guida per AI Agent (Agentic)

Scenario: AI con accesso diretto alla codebase via IDE tools.

Capabilities Disponibili

L’AI Agent può:

  • ✅ Leggere/scrivere file

  • ✅ Eseguire comandi (git, pytest, mypy)

  • ✅ Navigare codebase

  • ✅ Run tests

  • ✅ Commit changes

Workflow Consigliato

Step 1: Planning

1. Leggi ROADMAP.md sezione del plugin target
2. Verifica architettura esistente in packages/core/
3. Identifica dependencies (altri plugin)
4. Crea implementation_plan.md artifact

Step 2: Implementation

1. Crea Protocol in packages/core/src/structum_lab/[nome]/interfaces.py
2. Crea __init__.py in packages/core/src/structum_lab/[nome]/
3. Crea package dir in packages/[nome]/
4. Crea src/structum_lab/ in packages/[nome]/src/structum_lab/
5. Implementa concrete class
6. Aggiungi health checks
7. Aggiungi metrics
8. Crea tests

Step 3: Integration

1. Update demo app in demo/
2. Create documentation in docs/
3. Update ROADMAP.md con progress
4. Run full test suite

Step 4: Quality

# L'AI deve eseguire questi comandi:
mypy src/ --strict
pytest tests/ -v --cov
ruff check src/
black --check src/

Comandi Chiave

# Setup
pip install -e packages/core
pip install -e packages/[nome]

# Development
pytest tests/ -v
mypy packages/*/src/ --strict
ruff check packages/*/src/

# Documentation
mkdocs serve

# Git
git add -A
git commit -m "feat(plugin): add [nome] package"
git push

File da Creare (Template)

Core Interface:

# packages/core/src/structum_lab/[nome]/interfaces.py
from typing import Protocol, Dict, Any

class [Nome]Interface(Protocol):
    """Protocol for [description]."""
    
    def operation(self) -> Any:
        """[Docstring]."""
        ...
    
    def health_check(self) -> Dict[str, Any]:
        """Return health status."""
        ...
    
    def shutdown(self) -> None:
        """Graceful shutdown."""
        ...

Plugin Implementation:

# packages/[nome]/src/structum_lab/provider.py
from structum_lab.[nome] import [Nome]Interface
from structum_lab.config import get_config
from structum_lab.monitoring import get_metrics
from structum_lab.logging import get_logger

class Concrete[Nome]([Nome]Interface):
    def __init__(self):
        self.cfg = get_config()
        self.metrics = get_metrics("structum.[nome]")
        self.log = get_logger(__name__)
        
        # Setup based on config

    def operation(self) -> Any:
        # Emit metrics
        self.metrics.increment("operations.total")
        self.log.info("Operation executed")
        ...

    def health_check(self) -> Dict[str, Any]:
        return {"status": "healthy"}

    def shutdown(self):
        self.log.info("Shutting down")
        # Cleanup

💬 Guida per AI Chat-based

Scenario: AI senza accesso diretto al codice, solo chat.

Context Necessario

L’utente deve fornire:

  1. Link a ROADMAP.md

  2. Sezione specifica del plugin da implementare

  3. File esistenti rilevanti (se modifiche)

AI Response Pattern

L’AI dovrebbe:

  1. Confermare comprensione del task

  2. Elencare file da creare

  3. Fornire codice completo per ogni file

  4. Includere comandi da eseguire

  5. Specificare test da scrivere

Example Interaction

User: “Implementa structum_database Phase 1 (SQLAlchemy)”

AI Response Structure:

## Implementation Plan

Files to create:
1. packages/core/src/structum_lab/database/interfaces.py
2. packages/core/src/structum_lab/database/__init__.py
3. packages/database/src/structum_lab/sqlalchemy.py
4. tests/test_database.py

## File 1: Core Interface

[Complete code block]

## File 2: Plugin Implementation

[Complete code block]

## Commands to Run

```bash
# Create directories
mkdir -p packages/database/src/structum_lab
mkdir -p packages/core/src/structum_lab/database

# Create files
[Step by step]

# Test
pytest tests/test_database.py -v

Next Steps

  1. Review code

  2. Run tests

  3. Update ROADMAP.md progress


---

## 🔄 Workflow Operativi

### Workflow 1: Nuovo Plugin (da Zero)

```markdown
1. READ: ROADMAP.md sezione plugin
2. CREATE: Core interface in packages/core/
3. CREATE: Package implementation in packages/
4. CREATE: Tests in tests/
5. CREATE: Documentation in docs/
6. UPDATE: Demo in demo/
7. RUN: Quality checks (mypy, pytest, ruff)
8. COMMIT: Changes with conventional commits
9. UPDATE: ROADMAP.md progress

Workflow 2: Estendere Plugin Esistente

1. READ: Existing plugin code
2. IDENTIFY: Integration points
3. EXTEND: Add new methods to interface
4. IMPLEMENT: New methods in concrete class
5. UPDATE: Tests
6. UPDATE: Documentation
7. RUN: Full test suite
8. COMMIT: Changes

Workflow 3: Fix Bug

1. READ: Bug report / failing test
2. LOCATE: Root cause in code
3. FIX: Issue with minimal change
4. ADD: Regression test
5. VERIFY: All tests pass
6. COMMIT: Fix with issue reference

✅ Quality Gates

Pre-commit (Obbligatori)

# Type checking
mypy src/ --strict
# Exit code must be 0

# Code formatting
black src/ --check
# Exit code must be 0

# Linting
ruff check src/
# Exit code must be 0

# Tests
pytest tests/ -v --cov --cov-report=term-missing
# Coverage must be >90%

Pre-merge (Obbligatori)

# All pre-commit checks +

# Integration tests
pytest tests/integration/ -v

# Documentation build
mkdocs build --strict

# Security scan
bandit -r src/

# Dependency check
safety check

Success Criteria

Un plugin è completo quando:

  • ✅ Protocol nel core

  • ✅ Almeno 1 implementazione concreta

  • ✅ Usato in almeno 1 demo

  • ✅ Documentazione completa

  • ✅ Test coverage >90%

  • ✅ Mypy strict passa

  • ✅ Security scan pulito

  • ✅ Health checks implementati

📝 Conventional Commits

Format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature

  • fix: Bug fix

  • docs: Documentation

  • refactor: Code refactoring

  • test: Test changes

  • chore: Maintenance

Examples:

feat(database): add SQLAlchemy provider
fix(auth): handle expired JWT tokens
docs(roadmap): update plugin priorities
refactor(cache): extract Redis client to separate class
test(messaging): add integration tests for pub/sub
chore(deps): update dependencies

🎯 Quick Reference

File Locations

Component

Location

Purpose

Core Interfaces

packages/core/src/structum_lab/

Protocol definitions

Package Implementations

packages/*/src/structum_lab/

Concrete implementations

Demos

demo/

Usage examples

Docs

docs/

MkDocs documentation

Tests

tests/

Test suite

Roadmap

ROADMAP.md

Development guide

Key Commands

# Development
pip install -e packages/core
pip install -e "packages/dynaconf[dev]"
pip install -e "packages/observability[dev]"

# Quality
mypy packages/*/src/ --strict && pytest tests/ -v && ruff check packages/*/src/

# Documentation
mkdocs serve  # http://localhost:8000

# Git
git add -A
git commit -m "feat(scope): description"
git push origin main

Key Files to Read First

  1. ROADMAP.md - Complete development guide

  2. packages/core/src/structum_lab/config/interface.py - Example protocol

  3. packages/dynaconf/src/structum_lab/core/provider.py - Example implementation

  4. demo/01-logging-basics/ - Working demo

  5. docs/modules/monitoring.md - Documentation example

🚀 Getting Started (AI Checklist)

Prima di iniziare qualsiasi task:

  • [ ] Ho letto ROADMAP.md?

  • [ ] Ho capito l’architettura core/plugins?

  • [ ] So quale plugin devo implementare?

  • [ ] Ho verificato le dependencies?

  • [ ] Ho identificato i file da creare/modificare?

Durante implementation:

  • [ ] Sto seguendo il pattern Protocol → Implementation?

  • [ ] Sto usando get_config() per configuration?

  • [ ] Sto emettendo metrics?

  • [ ] Sto loggando con structured logger?

  • [ ] Ho aggiunto health checks?

  • [ ] Ho implementato graceful shutdown?

Prima di commit:

  • [ ] mypy passa?

  • [ ] pytest passa?

  • [ ] Coverage >90%?

  • [ ] Documentation aggiornata?

  • [ ] Demo aggiornata?

  • [ ] ROADMAP aggiornata?

Il progetto è AI-ready. Happy coding! 🤖✨