# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install ZCore with all optional dependencies
pip install fastapi-zcore-framework[all]

# Initialize a new project
zc init taskmanager
cd taskmanager

taskmanager/
├── main.py              # Application entry point & orchestration
├── .env                 # Project environment settings (including secure SECRET_KEY)
├── requirements.txt     # Dependencies list
├── .gitignore           # Python, IDE, and DB exclusions
└── zcore_dev.db         # Local development SQLite database

zc startapp tasks --template

tasks/
├── __init__.py
├── models.py            # SQLAlchemy Declarative Model
├── schemas.py           # Context-Aware Zchema Definitions
├── repositories.py      # Persistence & Query Layer
├── services.py          # Pure Business Logic & Lifecycle Hooks
├── routers.py           # Scaffolded CRUD Router
└── plugin.py            # Kernel Lifespan Plugin Wrapper

import uuid
from sqlalchemy import String, Boolean
from sqlalchemy.orm import Mapped, mapped_column
from zcore import Base

class Task(Base):
    __tablename__ = "tasks"

    id: Mapped[uuid.UUID] = mapped_column(primary_key=True, default=uuid.uuid4)
    title: Mapped[str] = mapped_column(String(255), index=True)
    description: Mapped[str | None] = mapped_column(String(1024), default=None)
    priority: Mapped[str] = mapped_column(String(50), default="medium")
    is_completed: Mapped[bool] = mapped_column(Boolean, default=False)
    assignee_email: Mapped[str | None] = mapped_column(String(255), default=None)

from pydantic import ConfigDict
import uuid
from zcore import Zchema

class TaskBase(Zchema):
    __model__ = "tasks"  # Binds schema to the "tasks" permission namespace

class TaskCreate(TaskBase):
    title: str
    description: str | None = None
    priority: str = "medium"
    assignee_email: str | None = None

class TaskUpdate(TaskBase):
    title: str | None = None
    description: str | None = None
    priority: str | None = None
    is_completed: bool | None = None
    assignee_email: str | None = None

class TaskResponse(TaskBase):
    id: uuid.UUID
    is_completed: bool

    model_config = ConfigDict(from_attributes=True)

from zcore import BaseRepository
from sqlalchemy.ext.asyncio import AsyncSession
from .models import Task
from .schemas import TaskCreate, TaskUpdate

class TaskRepository(BaseRepository[Task, TaskCreate, TaskUpdate]):
    def __init__(self, db: AsyncSession):
        super().__init__(model=Task, db=db)

from zcore import BaseService, Inject
from .models import Task
from .schemas import TaskCreate, TaskUpdate
from .repositories import TaskRepository

class TaskService(BaseService[Task, TaskCreate, TaskUpdate]):
    def __init__(self, repository: TaskRepository = Inject(TaskRepository)):
        super().__init__(model=Task, repository=repository)

    # --- Lifecycle Hooks ---

    async def pre_create(self, schema: TaskCreate) -> None:
        """Executed automatically inside the write pipeline before DB insertion."""
        if schema.priority not in ["low", "medium", "high"]:
            schema.priority = "medium"

    async def post_create(self, model: Task) -> None:
        """Executed after successful DB insertion, prior to transaction commit."""
        # Clean boundary for publishing events, audit logs, or notifications
        pass

from zcore import BaseRouter
from .schemas import TaskCreate, TaskUpdate, TaskResponse
from .services import TaskService
from .models import Task

class TaskRouter(BaseRouter[TaskCreate, TaskUpdate]):
    model = Task
    create_schema = TaskCreate
    update_schema = TaskUpdate
    schema_out = TaskResponse
    service = TaskService

    prefix = "/tasks"
    tags = ["Tasks"]
    expose_schemas = True  # Activates runtime schema introspection

# Instantiate for plugin integration
router_instance = TaskRouter()

from fastapi import FastAPI
from zcore import Plugin
from .routers import router_instance

class TaskPlugin(Plugin):
    name = "tasks"
    version = "0.1.0"
    dependencies = []  # Declare other plugin names that must boot up first

    def setup(self, app: FastAPI) -> None:
        # Mount the scaffolded APIRouter instance to the FastAPI app
        app.include_router(router_instance.router)

    async def on_startup(self) -> None:
        """Standard startup lifecycles (e.g. warming up caches)"""
        pass

    async def on_shutdown(self) -> None:
        """Graceful cleanup tasks during application teardown"""
        pass

from fastapi import FastAPI
from zcore import Kernel, settings
from zcore.web import RequestLogMiddleware, ScopedDependencyMiddleware
from zcore.exceptions import app_exception_handler, AppException
from zcore.db import db_manager, register_db_event_dispatcher
from zcore.logging import setup_logging

from tasks.plugin import TaskPlugin

# 1. Initialize structured logging configuration
setup_logging()

# 2. Configure the database connection pool (SQLite development fallback)
db_manager.init_app(
    db_url=settings.DATABASE_URL,
    echo=(settings.ENVIRONMENT == "development")
)

# 3. Create the Kernel and register domain plugins
kernel = Kernel()
kernel.add_plugin(TaskPlugin())

# 4. Bridge database events to the central kernel dispatcher
register_db_event_dispatcher(kernel.dispatcher)

# 5. Create FastAPI app bound to ZCore's topological lifespan
app = FastAPI(
    title=settings.PROJECT_NAME,
    lifespan=kernel.lifespan
)

# 6. Finalize kernel plugin setups
kernel.setup(app)

# 7. Add core architectural middlewares & exception handlers
app.add_middleware(RequestLogMiddleware)
app.add_middleware(ScopedDependencyMiddleware)
app.add_exception_handler(AppException, app_exception_handler)

zc run

📡 Starting ZCore Dev Server on 127.0.0.1:8000...
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Application startup complete.