# Skeletone

A minimal, well-toned Python project skeleton and **micro-framework** for rapid backend development.  
Built on top of **FastAPI**, **SQLAlchemy**, and **Alembic** with automated template versioning, advanced logging, and production-ready features.

## Features

- 🚀 **FastAPI** foundation with modern Python async practices
- 🗄️ **SQLAlchemy (async)** ORM with **Alembic** migrations
- 🧩 **Minimal framework structure** with clear folder layout
- 📦 **Template management**: init, upgrade, downgrade, version lock
- 📄 **Patch-based updates** between template versions (v1.1.0 to v1.9.0)
- 🔁 **Incremental version tracking** via `skeletone.lock`
- 📊 **Advanced Request Logging**: All incoming API requests logged to database
- 🧾 **Batch Logging System** with async buffer and periodic flush (v1.4.0+)
- 🛡️ **Bulkhead Pattern** middleware for concurrency control (v1.9.0+)
- 🔄 **Lifespan Management** for startup/shutdown tasks
- ⚡ **Production-ready** - optimized for performance and reliability

## What's New in Latest Versions

### v1.9.0
- ✨ **Bulkhead Middleware**: Control max concurrent requests to prevent overload
- 🏗️ Restructured middleware organization

### v1.8.0 - v1.7.0
- 📝 Enhanced logging service architecture
- 🔧 Improved lifespan management

### v1.6.0 - v1.4.0  
- 🚀 **Batch Logging**: Logs are buffered and flushed periodically for better performance
- ⏱️ Async logging with configurable flush intervals
- 🔄 Graceful shutdown with log flushing

### v1.3.0 - v1.1.0
- 📊 Initial request logging to database
- 🏛️ Base project structure with FastAPI + SQLAlchemy

## Installation

```bash
pip install skeletone
```

## Quick Start

### 1. Initialize a New Project

```bash
mkdir my-awesome-api && cd my-awesome-api
skeletone init
```

### 2. Check Available Versions

```bash
skeletone versions
```

### 3. Upgrade Your Project

```bash
skeletone upgrade
```

### 4. Rollback if Needed

```bash
# Interactive version selection
skeletone downgrade

# Or specify version directly
skeletone downgrade -v v1.2.0
```

## CLI Commands

| Command             | Description                                |
|---------------------|--------------------------------------------|
| `skeletone init`     | Initialize new project from latest template |
| `skeletone upgrade`  | Upgrade to latest template version         |
| `skeletone downgrade`| Downgrade to a previous template version   |
| `skeletone versions` | List all available template versions       |
| `skeletone help`     | Show detailed help and usage examples      |

## How It Works

Skeletone is built around a **patch-based versioning system**:

- **Init**: Sets up a fresh project from the latest template (currently v1.9.0)
- **Upgrade**: Applies sequential `.patch` diffs to upgrade your project
- **Downgrade**: Applies reverse patches to safely revert
- **Track**: Saves current version to `skeletone.lock`

## Template Structure

The generated project includes:

```
your-project/
├── app/
│   ├── models/          # SQLAlchemy models (async)
│   ├── routers/         # FastAPI route handlers
│   ├── dependencies/    # DI system & authorization
│   ├── services/        # Business logic & logging service
│   ├── middlewares/     # Request logging & bulkhead pattern
│   ├── lifespan/        # Startup/shutdown management
│   └── utils/           # Enums, configs, helpers
├── alembic/             # Database migrations
├── config.py            # App settings
├── main.py              # FastAPI application entrypoint
├── requirements.txt     # Dependencies
└── skeletone.lock       # Template version lock file
```

## Key Components

### 🛡️ Bulkhead Middleware (v1.9.0+)
Prevents system overload by limiting concurrent requests:
```python
app.add_middleware(BulkheadMiddleware, max_concurrent_requests=40, timeout=0)
```

### 📊 Advanced Logging System
- **Request Logger**: Automatically logs all HTTP requests with path, method, status, response time
- **Batch Processing**: Logs are buffered and flushed periodically for optimal performance
- **Database Storage**: All logs stored in PostgreSQL for analysis
- **Async Everything**: Non-blocking logging that doesn't impact response times

### 🔄 Lifespan Management
Clean startup and shutdown handling:
- Initialize services on startup
- Gracefully close connections on shutdown
- Flush pending logs before termination

## Example Workflow

```bash
# Create and initialize a new project
mkdir blog-api && cd blog-api
skeletone init

# Do your development work...

# Upgrade to latest version (v1.9.0)
skeletone upgrade

# Check available versions
skeletone versions
# Shows: v1.9.0 (current), v1.8.0, v1.7.0, ... v1.1.0

# Rollback if needed
skeletone downgrade -v v1.1.0
```

### Version Table Example

```text
Available Skeletone Versions
┌─────────┬─────────────┐
│ Version │ Status      │
├─────────┼─────────────┤
│ v1.9.0  │ ✅ Current   │
│ v1.8.0  │             │
│ ...     │             │
│ v1.1.0  │             │
└─────────┴─────────────┘
```

## Best Practices

1. **Always commit** your code before upgrade/downgrade
2. **Review diffs** and changes after updating
3. **Thoroughly test** after version transitions
4. **Track your modifications** to avoid patch conflicts
5. **Configure bulkhead** limits based on your server capacity
6. **Monitor logs** regularly for performance insights

## Template Repository

The base template for Skeletone lives here:  
👉 **[https://github.com/yoursteacup/skeletone](https://github.com/yoursteacup/skeletone)**

## Contributing

Contributions are welcome! Please see the GitHub repo for guidelines and issue tracking.

## Author

**Developer**: Zhaxybayev Daulet  
**GitHub**: [yoursteacup](https://github.com/yoursteacup)  
**Telegram**: [@yoursteacup](https://t.me/yoursteacup)
