Mr-DooSun/fastapi-agent-blueprint

This system is a modular, domain-driven Python framework designed to scaffold and manage complex backend applications with a strong emphasis on AI integration and strict governance. It provides a standardized architecture for building services that handle user authentication, administrative operations, and background task processing, while offering built-in infrastructure for Retrieval-Augmented Generation (RAG), vector storage, and LLM guardrails. The platform enforces safety and code quality through automated hooks, structured logging, and comprehensive observability, serving as both a production-ready application skeleton and a collection of runnable examples for common patterns like chatbots and webhooks.

Users can now run database migrations for DynamoDB tables using the new CLI entry point at \migrations/dynamodb/cli.py\. This tool automatically discovers \DynamoModel\ subclasses across the project's domain directories and applies schema changes, including creating new tables, updating Global Secondary Indexes (GSI), and configuring Time-To-Live (TTL) settings. The migration process relies on the \boto3\ library, which must be installed via the \aws\ extra (e.g., \uv sync --extra aws\), and requires environment configuration files located in the \\_env\ directory.

migrations/dynamodb · high confidence

The observability module now includes bootstrap and setup logic to initialize OpenTelemetry tracing when enabled. This configures a global TracerProvider with an OTLP gRPC exporter and automatically instruments all PydanticAI Agent instances to emit GenAI semantic-convention spans. The implementation is idempotent and safe to run even if the OpenTelemetry or PydanticAI extras are not installed, logging warnings instead of crashing.

_src/\core/infrastructure/observability · high confidence

A new CLI tool and migration engine have been added to manage S3 Vectors indexes. The \migrations/s3vectors\ module provides a scanner to auto-discover VectorModel subclasses and a migrator that creates, updates, or deletes indexes based on model definitions, including support for listing existing indexes and cleaning up orphaned ones.

migrations/s3vectors · high confidence

The notification infrastructure now supports sending error alerts to Slack and Discord webhooks, replacing the previous no-op fallback. Alerts are gated by a configurable severity threshold and an in-memory cooldown to prevent spam. A new routing layer allows critical and warning-level errors to be sent to separate webhook URLs based on their status code. Additionally, a Taskiq middleware has been added to monitor background worker tasks, dispatching alerts for terminal failures while respecting retry logic and applying task-scoped cooldowns to ensure distinct tasks do not mute each other's notifications.

_src/\core/infrastructure/notification · high confidence

This change introduces a complete Todo domain example within the \examples/todo\ directory, mirroring the existing \src/user\ architecture. It adds the server-side interface components, including FastAPI routers for creating, listing, retrieving, updating, and deleting todos (exposed at \/v1/todo\), Pydantic schemas for request/response validation, and a bootstrap module to wire the application. It also includes the infrastructure layer with SQLAlchemy 2.0 models (\TodoModel\), a repository implementation, and dependency injection containers, providing a runnable end-to-end example of the framework's patterns.

examples/todo/interface · high confidence

The \examples/url\_shortener\ directory now contains a complete, runnable example demonstrating a domain service shared between an HTTP interface and a background worker. It provides a REST API for creating, reading, and deleting short links, alongside a Taskiq-based cleanup task that automatically removes expired entries. The example includes all necessary domain models, repositories, dependency injection wiring, and server/worker bootstrapping code, serving as a reference for implementing similar domain-driven architectures.

_examples/url\shortener · high confidence

Introduces a new multi-turn chatbot example that persists conversation history to a database and replays it into the agent on each call, providing the LLM with full session context. The example includes a FastAPI interface with endpoints to send messages and retrieve history, a PydanticAI-based infrastructure adapter for real LLM calls (with a deterministic stub fallback), and a structured output schema that enforces a confidence score between 0.0 and 1.0.

_examples/chatbot\_with\memory · high confidence

The Todo example now includes a structured domain layer consisting of a Pydantic data transfer object (TodoDTO), a repository protocol interface, and a service class that implements CRUD operations using the project's base service and repository abstractions.

examples/todo/domain · high confidence

A new minimal Todo CRUD example has been added to the \examples/todo\ directory, mirroring the layout of the existing \src/user\ example. This reference code provides endpoints for creating, listing, retrieving, updating, and deleting todos, along with a README containing quick-start curl commands. Note that this example is not auto-wired into the application and must be manually copied to \src/todo/\ or bootstrapped to run.

examples/todo · high confidence

The application now includes a \BodySizeLimitMiddleware\ that rejects oversized request bodies (returning 413) by checking the \Content-Length\ header and counting bytes during streaming, preventing unauthenticated callers from triggering expensive parsing of large payloads. Additionally, a new \HttpClient\ implementation using \aiohttp\ has been introduced, featuring environment-specific timeout and connector configurations, event loop tracking to handle session lifecycle changes, and curated error handling that exposes only safe origin details in response bodies while logging full context for debugging.

_src/\core/infrastructure/http · high confidence

A new simple\_chatbot example has been added to demonstrate a minimal, stateless PydanticAI Agent within the blueprint's 3-tier DDD architecture. This example introduces a structured output model (ChatReply) that enforces a confidence score between 0.0 and 1.0, and persists chat interactions (prompt, reply, and token usage) to a SQLite database via a dedicated repository. It includes a real LLM adapter using PydanticAI, a deterministic stub fallback for environments without an LLM provider, and FastAPI endpoints for sending messages and retrieving historical replies.

_examples/simple\chatbot · high confidence

The admin interface now includes dedicated pages for managing user records, accessible at /admin/user for the list view and /admin/user/{record\_id} for details. These pages are protected by authentication (require\_auth) and feature centralized error handling via admin\_error\_boundary. The layout is consistent with other admin pages, using the shared admin\_layout component and injecting page configurations discovered at bootstrap.

src/user/interface/admin/pages · high confidence

Introduces a new example application that demonstrates an agentic tool-use workflow within the blueprint's 3-tier DDD architecture. The chatbot uses a PydanticAI Agent to automatically invoke a keyless DuckDuckGo web search tool when answering questions requiring up-to-date information. It persists conversation history to a dedicated \web\_search\_chatbot\_message\ database table and exposes endpoints for sending prompts and retrieving historical replies, including a deterministic stub fallback for local testing without an LLM provider.

_examples/web\_search\chatbot · high confidence

The \src/\_core/domain\ module now includes a new \validation.py\ file providing reusable primitives for validating business logic during Create, Read, Update, and Delete operations. This includes helpers for raising structured validation errors (\ValidationFailed\, \raise\_if\_errors\), checking conditionally required fields (\ensure\_conditionally\_required\), and detecting duplicates or uniqueness violations against a repository (\collect\_duplicate\_field\_errors\, \collect\_unique\_field\_errors\, \collect\_existing\_unique\_field\_errors\). These tools allow adopters to enforce data integrity rules consistently across their domain models.

_src/\core/domain · high confidence

The infrastructure layer now includes a new auto-discovery utility that scans the src/ directory to automatically detect valid domain packages. A domain is considered valid if it contains an \_\init\\_.py file and a specific DI container file (infrastructure/di/{name}\_container.py). This allows the application's DI containers and bootstrap process to load domains without requiring manual registration, simplifying the addition of new domains.

_src/\core/infrastructure · high confidence

The \.agents/shared/governor\ package has been introduced as the single source of truth for agent governance logic, replacing duplicated implementations across Claude, Codex, and Antigravity hook adapters. This change centralizes safety checks (including SQL injection, hardcoded secret, and domain-layer import detection), stage-gate policies (mid-task scope expansion and plan-to-execute boundaries), completion-gate logic (Pillar 7 footer requirements), and locale-resolved reminder strings. By consolidating these components, the system ensures consistent behavior across all agent tools and simplifies future policy updates.

.agents/shared/governor · high confidence

The server now exposes a new \/v1\ API for querying AI usage logs, available when the \ai\_usage\_public\_api\_enabled\ setting is true. This includes endpoints to list individual usage logs with pagination and filtering (by organization, agent, model, status, guardrail triggers, and date range), retrieve a summary of usage statistics broken down by organization, and fetch a specific log entry by ID. The API returns structured data including token counts, costs, and provider metadata while explicitly excluding sensitive content like raw prompts or model outputs from the metadata field.

_src/ai\usage/interface/server · high confidence

The repository is initialized with the baseline codebase and a comprehensive set of configuration files to establish the development environment and AI collaboration governance. This includes \.claudeignore\ and \.codexignore\ to manage tool-specific file exclusions, \.dockerignore\ to optimize container builds, and \.gitleaks.toml\ to extend secret scanning with a specific rule for Discord webhook URLs. A \.pre-commit-config.yaml\ is added to enforce linting, formatting, and architectural constraints (such as prohibiting Domain-to-Infrastructure imports) via Ruff and custom Python scripts. Additionally, \AGENTS.md\ and \CLAUDE.md\ define the shared project rules, default coding flow, and tool-specific harness guidance, while \.mcp.json\ configures the Context7 MCP server for Claude. Standard documentation files like \CHANGELOG.md\, \CONTRIBUTING.md\, and \CODE\_OF\_CONDUCT.md\ are also included to structure project metadata and contributor guidelines.

(repo-wide) · high confidence

This change introduces the initial directory structure for the new AI usage ledger domain. It creates the necessary Python package files (empty \_\init\\_.py) under src/ai\_usage and its sub-packages (interface, admin, worker, bootstrap, payloads, tasks), establishing the foundation for the feature without adding functional code in this specific location.

(repo-wide) · high confidence

This change adds the infrastructure layer for a new AI usage ledger, including the database schema, repository, and dependency injection container. The schema introduces a new \ai\_usage\_log\ table that tracks detailed usage metrics (tokens, duration, cost) and, crucially, a \guardrail\_triggered\ boolean field to support Phase 5 guardrail observability and red-team monitoring. To address privacy requirements, the \usage\_metadata\ column is explicitly documented to store only provider usage metadata, excluding raw prompts, model outputs, user input, and raw error text. The repository implements idempotent insertion logic to handle duplicate calls safely and provides query capabilities filtered by status, guardrail triggers, and time ranges.

_src/ai\usage/infrastructure · high confidence

Adds a new project-local harness adapter that integrates the existing shared governance and workflow policies with Gemini CLI via the Antigravity 2.0 plugin system. This includes a set of hooks (session-start, user-prompt-submit, pre-tool-security, post-tool-format, completion-gate, stop-sync-reminder, verify-first) that enforce code safety, format Python files with Ruff, manage session state, and provide governance reminders. Configuration files for permissions, MCP servers (Context7), and plugin metadata are also added to wire these capabilities into the Gemini CLI environment.

.antigravity · high confidence

This change adds a new DynamoDB persistence implementation under src/\_core/infrastructure/persistence/nosql, including a base repository, client wrapper, and model serialization utilities. It introduces specific exception types for DynamoDB operations (e.g., throttling, condition failures, batch incompleteness) to provide accurate HTTP status codes to clients. A key behavioral improvement is the removal of AWS provider messages (which may contain sensitive IAM ARNs) from structlog kwargs, ensuring compliance with security guidelines while still logging errors via exception chains. The implementation also includes exponential backoff with jitter for batch retries and strict validation for pagination cursors and limits.

_src/\core/infrastructure/persistence/nosql · high confidence

This change introduces the new \src/\_core/infrastructure/persistence/rdb\ module, establishing the core infrastructure for relational database operations. It adds a \Database\ class that manages both synchronous and asynchronous SQLAlchemy engines, supporting PostgreSQL, MySQL, and SQLite with environment-specific connection pooling and timeout configurations. A \BaseRepository\ is provided to standardize CRUD operations, featuring engine-parity fixes for default value reloading and stable sorting. Additionally, the module integrates \structlog\ for consistent SQL query logging and ensures domain exceptions are correctly propagated rather than masked as generic server errors.

_src/\core/infrastructure/persistence/rdb · high confidence

Added a new S3 Vectors backend implementation for the vector store infrastructure, including the S3VectorClient wrapper, base store logic, and specific exception types. This enables users to store and search vector embeddings using AWS S3 Vectors, with support for batched upserts, searches, and deletions, while ensuring sensitive AWS error details are handled securely in logs.

_src/\core/infrastructure/vectors/s3 · high confidence

The User domain now includes a persistent database model (UserModel) that enforces unique constraints on both the username and email fields. The model defines core user attributes including full name and password, and automatically manages creation and update timestamps.

src/user/infrastructure/database · high confidence

A new UserDTO class has been added to the user domain to serve as the structured data transfer object for user information. This DTO defines the schema for user attributes including unique identifier, username, full name, email address, password, and creation/update timestamps, replacing the previous entity pattern with a Pydantic-based model for consistent data handling.

src/user/domain/dtos · high confidence

Added the SQLAlchemy model for the new admin audit log table, which records persistent, append-only evidence of admin actions such as logins, account management, and password changes. The model uses a denormalized \\admin\_username\\ as the durable actor reference to ensure records survive admin deletion, while \\admin\_user\_id\\ is stored without a foreign key constraint to prevent incorrect cross-realm correlations and preserve data integrity against non-audit code paths. The schema includes fields for action details, state diffs, and metadata, with composite indexes optimized for time-ordered listing and filtering by actor, action, or domain.

_src/\core/infrastructure/admin/audit/models · high confidence

The admin interface now uses a centralized component library (src/\_core/infrastructure/admin/components) to ensure consistent styling and reduce duplication. This library provides standardized builders for page headers, cards, data grids, charts, forms, dialogs, and feedback, replacing ad-hoc NiceGUI element construction. Pages now compose these shared components to maintain a uniform look and feel across the admin dashboard.

_src/\core/infrastructure/admin/components · high confidence

The \src/ai\_usage/domain\ package now provides the core domain logic for tracking AI usage. It defines data transfer objects for detailed usage logs (including token counts, costs, and guardrail status) and summaries, alongside a repository protocol for inserting and querying these records. The service layer enforces an append-only policy: while usage can be recorded and queried with various filters (by org, agent, model, status, etc.), any attempt to update or delete existing usage logs will raise an error, ensuring data immutability.

_src/ai\usage/domain · high confidence

This change establishes the core infrastructure for the NiceGUI-based admin dashboard. It introduces a mandatory authentication gate (require\_auth) that validates sessions and redirects unauthorized users, backed by an AdminAuthProvider that records login attempts in a new audit log system. The audit log captures actions like LOGIN, ACCOUNT\_CREATE, and VIEW\_LIST/DETAIL with orthogonal action/result enums, ensuring no raw exception messages are exposed. A centralized error handler sanitizes user-facing messages while logging full details server-side, and a BaseAdminPage template method standardizes CRUD list/detail views with loading skeletons and optional read-event auditing. The admin shell features a responsive sidebar with dark mode toggle, and the theme system uses a single neutral-mono palette (Tailwind zinc/blue) with CSS custom properties for consistent light/dark theming across all admin pages.

_src/\core/infrastructure/admin · high confidence

The application now exposes a dedicated \AuthUseCase\ within the authentication layer to handle core identity operations. This component orchestrates user registration, credential-based login, token refresh, and logout by coordinating with the underlying authentication service and user domain. Users can now register new accounts and authenticate via username and password, receiving JWT access and refresh tokens upon successful completion of these flows.

src/auth/application · high confidence

Added a new \examples/\ directory containing a \README.md\ that documents how to run, contribute to, and evaluate small, self-contained example applications. The documentation clarifies the copy-flow mechanism for installing examples into \src/\, distinguishes between DB-only and LLM-calling examples, and outlines the required structure (code, README, unit tests) for new contributions. The directory also includes an \\_\init\\_.py\ to make it a package, and the README lists available examples such as \todo\, \url\_shortener\, \blog\, \webhook\_receiver\, and various chatbot patterns.

examples · high confidence

Added a new infrastructure module for recording admin actions, providing a persistent audit trail for administrative activities. The system includes a database model and repository for storing audit entries, ensuring that write failures are logged with sufficient context rather than silently dropped. It features a whitelist-based serializer for capturing before/after state snapshots of admin identities, explicitly excluding sensitive fields like password hashes to maintain security. The implementation supports lazy database resolution to avoid container state issues and normalizes timezone handling for retention cleanup tasks.

_src/\core/infrastructure/admin/audit · high confidence

The application now supports persisting refresh tokens in the database and revoking them. A new \RefreshTokenModel\ defines the storage schema, including fields for the token hash, JTI, expiration, and a \revoked\_at\ timestamp. The \RefreshTokenRepository\ provides methods to look up tokens by JTI and to revoke tokens either individually or for all active tokens belonging to a specific user. These infrastructure components are wired into the dependency injection container, enabling the authentication service to manage token lifecycle and security.

src/auth/infrastructure · high confidence

Added three new shared components to the .agents/shared directory: a shell launcher (harness-python.sh) that resolves and executes Python scripts using a virtual environment, uv, or system interpreters with a minimum version requirement of 3.12.9; a Python debug logger (harness\_debug.py) that sanitizes sensitive data from diagnostic output; and a work ledger module (work\_ledger.py) that persists agent state, including goals, plans, and verification status, to a JSON file to maintain context continuity across sessions.

.agents/shared · high confidence

The auth interface now exposes a dedicated set of REST endpoints under /v1/auth for user registration, login, token refresh, and logout, alongside a /v1/auth/me route to retrieve the current user profile. Authentication is handled via a FastAPI dependency that validates Bearer tokens and automatically binds the user ID to the structured logging context, ensuring that all request logs (including guardrail telemetry) carry the user identifier for better observability.

src/auth/interface · high confidence

The application now includes a new set of base Data Transfer Objects (DTOs) in the core module to standardize request and response handling. This introduces BaseRequest and BaseResponse classes with specific Pydantic configurations: API-facing models ignore extra fields and use camelCase aliases, while payload models forbid extra fields. Additionally, structured response types like SuccessResponse and ErrorResponse are provided, along with pagination metadata classes (PaginationInfo and CursorPaginationInfo) to support both offset-based and cursor-based pagination, particularly for DynamoDB-backed endpoints.

_src/\core/application/dtos · high confidence

A new asynchronous worker task, \consume\_task\, has been added to handle user-related background jobs. This task accepts a \UserTestPayload\ containing user identifiers and uses the \UserService\ to retrieve data by ID. The implementation is wired via dependency injection and registered with the task broker using a configurable prefix from the application settings.

src/user/interface/worker/tasks · high confidence

The auth domain now includes an AuthService that handles credential verification, JWT issuance, and refresh token rotation. Users can now have their refresh tokens revoked individually or in bulk for a specific user ID, and the system enforces token revocation checks during rotation. This change adds specific exceptions for invalid credentials, expired tokens, and revoked refresh tokens, along with DTOs for managing refresh token data.

src/auth/domain · high confidence

The \src/user/interface/server/schemas\ module now defines Pydantic models that enforce input validation and structure API payloads. \CreateUserRequest\ and \UpdateUserRequest\ specify field constraints, including length limits for usernames and full names, email format validation via \EmailStr\, and password requirements. \UserResponse\ defines the shape of user data returned to clients, including identifiers, profile details, and timestamps. These schemas serve as the contract for user-related API endpoints.

src/user/interface/server/schemas · high confidence

This change introduces the admin interface pages for the AI Usage domain, providing users with the ability to monitor and inspect AI usage data. It adds a list view at /admin/ai\_usage for browsing records, a summary view at /admin/ai\_usage/summary displaying key metrics (calls, requests, tokens) and a breakdown by organization, and a detail view at /admin/ai\_usage/{record\_id} for individual record inspection. These pages are integrated into the centralized admin layout, enforce authentication via the session system, and utilize the new centralized error handling and design-system components.

_src/ai\usage/interface/admin/pages · high confidence

An admin interface page titled 'AI Usage' has been added, providing a read-only, sortable, and searchable table of AI interaction data. Users can now view key metrics including call and request IDs, agent details, model usage, token counts, and provider costs. The dashboard specifically highlights whether guardrails were triggered, supporting the new guardrail observability features, and allows filtering by core identifiers like call ID, request ID, and model.

_src/ai\usage/interface/admin/configs · high confidence

The application now exposes a new landing page at /docs that allows users to choose between multiple API documentation viewers (Stoplight Elements, Scalar, Swagger UI, ReDoc, RapiDoc) with a GitHub-flavoured UI supporting light/dark themes. Additionally, two new health check endpoints are available: /health for a general status check and /health/db to verify database connectivity.

_src/\core/application/routers · high confidence

This change introduces the \admin\identity\ bounded context, providing a complete admin authentication and identity management system. It adds a dedicated admin-realm JWT token flow (login, refresh, logout) via FastAPI routes at \/v1/admin/\\, distinct from the customer realm. The system supports creating the first admin account, managing subsequent admin accounts (create, delete, permission updates), and changing passwords, including a bootstrap setup flow for initial installation. It includes database models for admin identities and refresh tokens, domain services for credential verification and token issuance, and application use cases that enforce security guards such as preventing self-deletion and ensuring at least one admin with 'accounts' permission remains.

_src/admin\identity · high confidence

The admin interface now includes dedicated pages for managing admin accounts, viewing an audit log, and completing the initial setup wizard. The accounts page allows creating new admins, editing permissions, and changing passwords, with all actions logged to the audit trail. The audit log page provides a filtered, paginated view of admin actions with detail dialogs. The setup wizard guides the creation of the first administrator account from bootstrap credentials. These pages are integrated into the new admin shell and theme, with centralized error handling and loading states.

_src/\apps/admin/pages · high confidence

The application layer now includes a new \usage\_tracker\ module that provides context managers and classes to capture and record agent usage metrics. This allows the system to track detailed usage facts such as token counts, duration, costs, and guardrail triggers for each agent call, supporting observability and red-team analysis.

_src/\core/application · high confidence

The application now includes an asynchronous object storage layer (src/\_core/infrastructure/storage) that supports S3 and MinIO backends. This new service provides file upload, download, deletion, existence checks, presigned URL generation, and file listing capabilities. A key behavioral change is the secure handling of storage errors: provider-specific messages (which may contain sensitive data like IAM ARNs or account IDs) are now logged internally but omitted from user-facing responses, which instead return generic error codes. The service requires the optional 'aws' dependency (aioboto3) to be installed.

_src/\core/infrastructure/storage · high confidence

The domain services layer now includes \BaseService\ and \BaseDynamoService\ to standardize CRUD operations for relational and DynamoDB-backed domains respectively, with \BaseService\ exposing methods like \count\_datas\_by\_day\ and \get\_datas\ with pagination. Additionally, a new \RagPipeline\ class has been added to orchestrate Retrieval-Augmented Generation workflows, handling embedding, vector search, and answer generation via injected protocols.

_src/\core/domain/services · high confidence

Added a new \examples/blog\ example that implements two domains, \author\ and \post\, to demonstrate protocol-based cross-domain dependency injection. The \post\ domain depends on the \author\ domain via an \AuthorRepositoryProtocol\ rather than a direct import, mirroring the architecture of the \src/auth\ and \src/user\ domains. The example includes full CRUD endpoints for both domains, database models, and service layers, and is designed to be copied into the \src/\ directory to resolve absolute imports correctly.

examples/blog · high confidence

Added a new \chatbot\_with\_guardrails\ example that demonstrates how to protect LLM endpoints using runtime guardrails. The example implements input validation to block prompt injections (returning 400), output scanning to detect and block PII like email addresses and IPv4 addresses (returning 422), and observability logging for phone numbers and prompt leaks. It includes a kill-switch via the \GUARDRAILS\_ENABLED\ environment variable, a unique database table name to avoid conflicts, and a bounded confidence score for chat replies.

_examples/chatbot\_with\guardrails · high confidence

Added \scripts/demo.sh\ and \scripts/demo-rag.sh\ to provide end-to-end quickstart demonstrations for the user domain and RAG features respectively. These scripts now enforce strict response envelope assertions, ensuring that API calls fail visibly if they do not return a success status, which prevents silent failures during local development. \scripts/demo.sh\ also introduces a \scripts/seed\_demo\_admin.py\ utility to programmatically create a fully privileged admin account for the admin-realm, enabling user CRUD operations in the demo environment that were previously blocked by authentication guards. Additionally, \scripts/create-langfuse-env.sh\ generates a secure, randomized local Langfuse environment file, while \scripts/record-demo-gif.sh\ and \scripts/render-diagrams.sh\ provide tooling to record optimized demo GIFs and render architecture diagrams to SVG for better documentation compatibility.

scripts · high confidence

This change introduces a set of new protocol interfaces in the domain layer to define backend-agnostic contracts for core infrastructure components, including repositories (BaseRepositoryProtocol, BaseDynamoRepositoryProtocol), vector stores (BaseVectorStoreProtocol), embeddings (BaseEmbeddingProtocol), and notifications (BaseNotificationProtocol). It also adds specific service protocols for admin CRUD operations (AdminCrudServiceProtocol) and agent usage recording (AgentUsageRecorderProtocol), alongside a new protocol for the RAG answer agent (AnswerAgentProtocol). To support the RAG pipeline, new Pydantic-based Data Transfer Objects (BaseChunkDTO, CitationDTO, QueryAnswerDTO) are added to handle data flow between the embedder, vector store, and answer agent, enabling structured answers with citations.

_src/\core/domain/protocols · high confidence

This change introduces a comprehensive set of immutable domain value objects in the core domain layer to support new AI and data capabilities. Key additions include AgentUsageRecord for tracking AI agent call metrics and guardrail triggers, EmbeddingConfig and LLMConfig for managing model and provider settings (including Bedrock credentials), and VectorQuery/VectorSearchResult to define vector similarity search parameters and results. The update also adds QueryFilter for paginated query sorting and searching, CursorPage for DynamoDB pagination, DynamoKey for item key management, and DailyCount for date-grouped aggregates. These objects standardize how configuration, search, and usage data are structured and validated across the application.

_src/\_core/domain/value\objects · high confidence

The internal core module (src/\_core) has been introduced, containing the application's centralized Settings class and vector storage infrastructure. The Settings class now manages configuration for the admin dashboard (including bootstrap credentials and dark mode defaults), JWT authentication (with separate realms for admin and customer tokens), and environment-specific validation. Additionally, new Pydantic models for vector data (VectorModel, VectorModelMeta) have been added to support S3 Vectors integration, defining schema metadata and serialization logic for embedding indices.

_src/\core · high confidence

This change introduces a suite of new Python-based checkers and utilities in the \tools/\ directory to enforce repository policies and operational safety. A new \check\_doc\_links.py\ validates relative Markdown links and anchor fragments against the git index to prevent broken references. Governance is strengthened by \check\_governor\_footer.py\, which validates the structure and field values of the new PR description footer block, and \check\_language\_policy.py\, which enforces the Tier 1 policy by detecting unauthorized Korean prose in shared paths. Operational safety is improved with \check\_migration\_safety.py\, an advisory checker for zero-downtime DDL compliance in Alembic migrations, and \check\_examples\_copyflow.py\, which prevents absolute imports in example code that would break after copying. Additionally, \check\_harness\_hook\_surface.py\ ensures agent hooks use proper Python interpreters, \check\_state\_lifecycle.py\ prevents state files from being committed to version control, and \governor\_state\_doctor.py\ provides a comprehensive diagnostic for governor state health. Finally, \migrate\_legacy\_revision\_ids.py\ provides a migration path for databases holding outdated Alembic revision IDs.

tools · high confidence

The \src/\_core/common\ module now provides shared infrastructure for the application. It introduces a realm-agnostic JWT codec (\JwtTokenCodec\) that allows separate admin and customer authentication realms to share crypto primitives while maintaining distinct trust boundaries. Security is hardened by moving bcrypt password hashing and verification off the event loop into worker threads to prevent process-wide stalls, and by adding a constant-time verification path (\verify\_or\_dummy\) to mitigate timing-based user enumeration. Additionally, the module includes helpers for pagination, text chunking (using \semantic\_text\_splitter\ and \tiktoken\ for embeddings), and UUID generation for vector IDs.

_src/\core/common · high confidence

A new classification capability is introduced, exposing a POST /v1/classify endpoint that accepts text and optional category constraints. The service returns a predicted category, a confidence score (0–1), and brief reasoning. Under the hood, it uses a clean architecture: a domain service delegates to a classifier protocol, which is implemented by a PydanticAI-based LLM classifier (with prompt-injection guardrails and usage tracking) or a deterministic stub when no LLM is configured. The feature includes domain DTOs, infrastructure wiring via a DI container, and FastAPI route registration, with authentication applied at the router level.

src/classification · high confidence

Added a runnable example in \examples/webhook\_receiver\ that demonstrates receiving webhooks via a FastAPI endpoint and processing their payloads asynchronously using a Taskiq background worker. The example includes the full domain layer (DTOs, repository protocol, service), infrastructure components (SQLAlchemy model, repository, dependency injection container), and interface code (API router, worker task, and bootstrap scripts). It shows how to enqueue a job immediately after receiving a webhook, allowing the API to return a fast response while the worker updates the event status from 'pending' to 'processing' and finally 'done'. The README explains how to run the example using the quickstart environment, including the limitation of the InMemoryBroker and instructions for configuring a cross-process broker like RabbitMQ.

_examples/webhook\receiver · high confidence

A new \quickstart.env.example\ file provides a zero-configuration setup for rapid local testing, using SQLite, an in-memory broker, and stub providers so the application can run without external infrastructure or API keys. The existing \local.env.example\ template has been expanded to document additional configuration options, including severity-based error notification routing, request body size limits, admin audit log retention, and the public AI usage ledger toggle.

_\env · high confidence

The RAG infrastructure layer now includes concrete adapters for answer generation and embedding. The PydanticAIAnswerAgent provides LLM-backed answers with structural prompt-injection detection on input and output PII fabrication checks (blocking email/IPv4, logging phone numbers). A StubAnswerAgent offers deterministic, templated responses when no LLM is configured, and a StubEmbedder provides keyword-based bag-of-words embeddings for demos and tests without external credentials.

_src/\core/infrastructure/rag · high confidence

The User module now includes a dedicated dependency injection setup via a new \UserContainer\. This container explicitly wires the \UserRepository\ and \UserService\, allowing the service to receive its repository dependency through the \core\_container\. This change centralizes the instantiation logic for user-related components, replacing ad-hoc imports with a structured DI pattern.

src/user/infrastructure/di · high confidence

The admin application now reuses the server's existing dependency injection tree instead of building a separate one. This change prevents resource duplication, such as creating duplicate database connection pools and HTTP clients, which previously exceeded the configured connection budget and caused duplicate warning logs. It also ensures that test overrides for the database apply consistently across both the API and admin routes.

_src/\apps/admin/di · high confidence

The admin landing page has been reworked to show what is wired up in the deployment and whether the system has data, replacing the previous activity chart and recent-activity table. A new operational-status facade reports which optional infrastructure components (database, broker, vector store, embedding, LLM, notifications, storage, DynamoDB, S3 Vectors, OpenTelemetry) are active, stubbed, or disabled, without exposing credentials. The dashboard also presents per-domain record counts, 7-day growth trends, and AI usage metrics (call volume, failure rate, tokens), with on-screen sections degrading gracefully to "Unavailable" if a backend read fails. Audit data is no longer shown on the landing page because the dedicated /admin/audit-log page provides a strict superset with filtering and pagination.

_src/\apps/admin · high confidence

The database schema now maintains a separate identity store for administrators (\admin\_identity\ and \admin\_refresh\_token\), moving admin accounts out of the general \user\ table to enforce a distinct authentication realm. To support this, the \admin\_audit\_log\ table had its foreign key to \user.id\ removed; this fixes a defect where authenticated admin actions were previously rejected and lost on PostgreSQL and MySQL because the ID space had shifted, ensuring the audit trail now reliably records all administrative activity.

migrations/versions · high confidence

The user management routes (create, read, update, delete) under /v1/user are now restricted to administrators. This change implements a default-deny policy by applying the require\_admin dependency to the entire router, ensuring that only admins can access these endpoints which expose other users' PII. Self-service profile reads remain available via /v1/auth/me.

src/user/interface/server/routers · high confidence

The migration environment has been refactored to allow Alembic to read database connection details (DATABASE\_ENGINE, DATABASE\_USER, etc.) directly from the process environment, rather than relying exclusively on local .env files. This change enables zero-config migration execution in containerized or CI environments where environment variables are injected at runtime, while still supporting local development via \env/\.env files. The migration runner now validates the ENV variable against a set of allowed values (quickstart, local, dev, stg, prod) and automatically loads all SQLAlchemy models from the src directory structure, including shared core models like the admin audit log.

migrations · high confidence

The \.codex/hooks\ directory has been rewritten as thin shims that import policy and logic from the shared \.agents/shared/governor\ module, replacing previous inline implementations. This change introduces several behavioral updates for Codex users: the PreToolUse hook now uses the shared \shell\_safety\ module to block dangerous commands; the UserPromptSubmit hook enforces safety-block-first parsing and writes exception markers; the Stop hook now emits localized sync reminders, verifies that tests were run (verify-first), checks for completion-gate conditions, and enforces a plan-to-execute stage gate; and the PostToolUse hook automatically formats Python files with Ruff and records verify commands to a session log. All hooks are fail-open, meaning import or execution failures in the shared governor or work-ledger modules will not crash the hook but will silently skip the associated policy check.

.codex/hooks · high confidence

The Docker image has been migrated to use the uv package manager for faster, more reliable builds, replacing the previous pip-based approach. Configuration is no longer baked into the image layers via static .env files; instead, it is injected at runtime through Docker Compose's env\_file mechanism, allowing environment-specific overrides (like prod settings) to take precedence without exposing secrets in the image history. The new multi-stage image also runs as a non-root user for improved security and includes necessary migration files and Alembic configuration directly in the container to support database upgrades.

_\docker · high confidence

The embedding layer has been replaced with a new PydanticAI-based adapter that standardizes how embedding requests are processed across providers like OpenAI and Bedrock. This change introduces specific error handling for common issues, including rate limits (429), authentication failures (401), missing models (404), and input size violations, ensuring users receive clear, structured error codes instead of generic exceptions. For OpenAI specifically, the adapter now implements intelligent batch splitting to respect token and item count limits, while Bedrock requests are handled with character-length validation.

_src/\core/infrastructure/embedding · high confidence

The UserRepository now intercepts database integrity errors during user creation and modification to provide clear, user-facing feedback. When a duplicate username or email is detected, the system raises a specific UserAlreadyExistsException instead of a generic database error, ensuring that validation failures are handled consistently across single and batch operations.

src/user/infrastructure/repositories · high confidence

The new in-memory vector store backend validates query filters before performing a search and raises a 400 error if the request uses operators it cannot honour (such as $gte, $lt, $and). Previously, unsupported operators were silently ignored, which could cause the store to return incorrect results or fail with a generic 500 error; the new behavior ensures that only the supported subset ($eq, $in, $ne) is processed, providing clear feedback to the caller when a filter is incompatible with this backend.

_src/\_core/infrastructure/vectors/in\memory · high confidence

The admin interface now uses a dedicated configuration file to define the User management page layout. This change separates the page definition (columns, search, and sort settings) from route handlers, providing a structured configuration for the User admin view that displays ID, username, full name, email, password, and timestamps.

src/user/interface/admin/configs · high confidence

The application now includes dedicated exception classes for user-related errors, specifically \UserNotFoundException\ (404) and \UserAlreadyExistsException\ (409). These exceptions provide structured error responses with specific error codes and messages, improving clarity when handling user lookup failures or duplicate username attempts.

src/user/domain/exceptions · high confidence

The user domain now exposes formalized protocol interfaces for its core components. A new \UserRepositoryProtocol\ extends the base repository contract to include an asynchronous method for retrieving user data by username, returning a \UserDTO\. Additionally, a \UserServiceProtocol\ defines the contract for creating user data, accepting a \CreateUserRequest\ schema and returning a \UserDTO\. These protocols standardize the interaction boundaries for user-related data access and creation within the application.

src/user/domain/protocols · high confidence

The LLM infrastructure layer now includes runtime prompt-injection and PII detection guardrails (guardrails.py) with standardized telemetry (guardrail\_telemetry.py) to block or log unsafe inputs and outputs. An Anti-Corruption Layer (error\_mapper.py) correctly maps provider-specific exceptions (including AWS Bedrock operations) to domain LLM errors, preventing misclassification of non-LLM failures. A model factory (model\_factory.py) supports Bedrock, OpenAI, and Anthropic providers with explicit credential handling, while a stub model (stub\_llm\_model.py) ensures graceful degradation when PydanticAI is not installed. Prompt boundaries (prompt\_boundaries.py) enforce XML escaping and instruction tails to prevent prompt injection via untrusted data.

_src/\core/infrastructure/llm · high confidence

The worker application has been rebuilt on Taskiq, replacing the previous Celery-based implementation. This change introduces a new bootstrap process that configures structlog, OpenTelemetry, and a middleware stack for task execution, including automatic retries and failure notifications. A new scheduled task has been added to automatically delete admin audit log entries older than the configured retention period, running daily at 03:00 UTC via the Taskiq scheduler. Additionally, the worker now fails fast with a clear error if launched with an InMemory broker, preventing crash-loops in standalone mode.

_src/\apps/worker · high confidence

The project now ships a suite of Claude Code hooks in \.claude/hooks\ that enforce coding standards and governance policies at the tool-use level. A new \check-required-plugins.sh\ hook warns users if \pyright-lsp\ is missing or if the \CONTEXT7\_API\_KEY\ is unset, ensuring code intelligence and rate-limit compliance. Security is strengthened by \pre-tool-security.sh\ and \pre\_tool\_security.py\, which block Edit/Write/Bash operations that introduce SQL injection, hardcoded secrets, or sensitive logs. Code quality is maintained via \post-tool-format.sh\, which automatically runs \ruff format\ and \ruff check --fix\ on Python files after edits. Governance is enforced through \pre-tool-stage-block.sh\ and \post\_tool\_stage\_gate.py\, which hard-block implementation edits when the workflow is in the 'planned' stage (enforcing the plan→execute boundary) and provide non-blocking advisory reminders for other stages. Additional hooks like \stop-sync-reminder.sh\ and \user-prompt-submit.sh\ manage sync guidelines and exception tokens, while \verify-first.sh\ and \verify-log.sh\ track verification state. All hooks are designed to be fail-open, ensuring that missing dependencies or import errors never block the user's workflow.

.claude/hooks · high confidence

A new rule file (.codex/rules/fastapi-agent-blueprint.rules) has been added to enforce safety constraints on AI-assisted development. The rules forbid dangerous operations like hard resets, discarding local changes, and recursive file removals, and require prompts for code pushes and database schema downgrades to prevent accidental data loss or state corruption.

.codex/rules · high confidence

The dependency injection container now uses selector functions to enable or disable optional services (storage, DynamoDB, S3 vectors, embedding, LLM, and notifications) based on configuration settings. Lazy imports are used inside factory functions so that missing optional dependencies (e.g., taskiq-aws, pydantic-ai) do not break application startup when those features are disabled. Notification wiring was consolidated to share a single client per channel instead of creating separate adapter instances per tier, and severity-based routing is opt-in via a warning threshold setting.

_src/\core/infrastructure/di · high confidence

The user module's internal directory structure has been reorganized to follow clean architecture principles. This change involves creating new empty \_\init\\_.py files to establish the package hierarchy under src/user/application (including use\_cases) and src/user/interface (including admin and server subdirectories). This refactoring prepares the codebase for better separation of concerns but does not introduce new user-facing features or change existing behavior.

(repo-wide) · low confidence

The application's core logic has been reorganized into a dedicated internal module named \_core, containing sub-packages for use cases, domain enums, and middleware. This change establishes a clear boundary for internal implementation details, separating them from public-facing interfaces or other application layers.

_src/\_core/application/use\_cases, src/\_core/domain/enums, src/\core/middleware · low confidence

The application structure has been refactored to support a modular architecture. This change introduces a new top-level \\_apps\ package and reorganizes the user worker interface into a dedicated \src/user/interface/worker\ module, establishing the foundational directory structure for this new organization.

_src/\apps, src/user/interface/worker · low confidence

The server entry point has been refactored to support a modular architecture where domains are discovered and bootstrapped dynamically at runtime. The new \src/\_apps/server\ module handles the core FastAPI application creation, middleware installation (including CORS, trusted hosts, and body size limits), and dependency injection container setup. A key behavioral change is the introduction of a dynamic domain discovery system that automatically loads and registers domain-specific routers and services, allowing new domains to be added without modifying the server's core bootstrap logic. Additionally, the inline task runtime is now installed within the server process to ensure consistent error handling and logging for in-memory broker tasks, and the application version is explicitly set to 0.11.1.

_src/\apps/server · high confidence

The user domain's server initialization logic has been consolidated into a dedicated bootstrap module. This change introduces a structured entry point that handles dependency injection wiring for the user routers and registers the user API routes under the /v1 prefix with the 'User' tag, replacing the previous ad-hoc or distributed setup methods.

src/user/interface/server/bootstrap · high confidence

The application now uses a centralized exception handling system in src/\_core/exceptions that standardizes error responses via ErrorResponse DTOs and integrates structured logging with structlog. Custom exceptions (BaseCustomException) and specific LLM errors (LLMException, LLMAuthenticationException, etc.) are mapped to appropriate HTTP status codes. The system automatically dispatches error notifications for server errors (5xx) and unhandled exceptions, while ensuring that sensitive guardrail details (PromptInjectionDetected, GuardrailBlocked) are never exposed in client responses. LLM provider errors are automatically mapped to domain-specific error codes, and validation errors return structured 422 responses.

_src/\core/exceptions · high confidence

The application now uses structlog for all logging, providing structured JSON output in production and colored console output in development. HTTP requests are logged via a new middleware that captures method, path, status code, and duration, while automatically injecting correlation IDs to link requests to background tasks. Background tasks handled by Taskiq now also emit structured logs, including failure events and task identifiers. Additionally, the retry middleware for background tasks has been refined to prevent retries on cancellation errors and to enforce proper backoff delays even when using the in-memory broker, ensuring transient failures are handled more reliably.

_src/\core/infrastructure/logging · high confidence

The user domain worker now initializes its dependency injection container by wiring the user test task module during startup. This change introduces a dedicated bootstrap entry point that ensures the necessary components are registered before the worker begins processing tasks.

src/user/interface/worker/bootstrap · high confidence

The new UserService in the user domain automatically hashes passwords before persisting them during user creation and updates, ensuring credentials are never stored in plain text. Additionally, the service now validates that usernames and emails are unique across the system for single and batch creation operations, as well as during updates, raising a specific exception if duplicates are detected.

src/user/domain/services · high confidence

Added E2E integration test for stop-sync-reminder hook marker cleanup; Added Locust performance-test harness; Added e2e tests for /docs selector and HTTP middleware contracts; Added e2e tests for admin auth API and realm separation; Added empty test package init files for user module; Added empty test package structure for admin identity integration tests; Added end-to-end tests for the /v1/classify endpoint; Added end-to-end tests for the AI usage API; Added end-to-end tests for the authentication API; Added end-to-end tests for user management and authentication; Added integration tests for AI usage repository; Added integration tests for DynamoDB persistence; Added integration tests for LLM guardrail observability and red-team safety; Added integration tests for classification stub fallback; Added integration tests for notification routing and optional infrastructure wiring; Added integration tests for refresh token repository; Added integration tests for user repository operations; Added minimal-install regression tests for optional extras; Added smoke tests for example copy-flow regression; Added test factories for core domain entities and schemas; Added tests for HTTP body size limiting middleware; Added tests for OpenAPI metadata contract; Added tests for RDB persistence contract, session error handling, and metadata completeness; Added tests for TaskIQ broker factory optional dependencies; Added tests for the server-side inline task runtime wiring; Added unit tests for AI usage domain and admin configuration; Added unit tests for AgentUsageRecord and PromptSnapshot validation; Added unit tests for CoreContainer optional-infrastructure selectors; Added unit tests for DynamoDB persistence layer; Added unit tests for LLM error mapping, prompt-injection guardrails, and prompt boundary escaping; Added unit tests for OpenTelemetry setup and configuration; Added unit tests for RAG infrastructure components; Added unit tests for URL shortener cleanup task; Added unit tests for admin bootstrap, container topology, dashboard metrics, and operational status; Added unit tests for admin identity and authentication services; Added unit tests for authentication use cases and services; Added unit tests for chatbot-with-memory example; Added unit tests for classification service, LLM config, and PydanticAI classifier guardrails; Added unit tests for core configuration validation and dead-code retention; Added unit tests for core domain services and validation logic; Added unit tests for exception handler logging, notifications, and guardrail safety; Added unit tests for local runner scripts; Added unit tests for logging configuration and Taskiq middleware behavior; Added unit tests for notification infrastructure; Added unit tests for object storage key handling and provider error curation; Added unit tests for repository tooling and configuration; Added unit tests for security helpers and text utilities; Added unit tests for the PydanticAI embedding adapter and configuration; Added unit tests for the Todo service; Added unit tests for the admin audit log system; Added unit tests for the agent usage tracker; Added unit tests for the blog example's post service; Added unit tests for the shared agents governance and harness logic; Added unit tests for the user service layer; Added unit tests for user admin configuration and router bounds; Added unit tests for vector store infrastructure; Added unit tests for webhook receiver event processing; Added unit tests for worker bootstrap, broker guards, and middleware ordering; New test support utilities for container wiring and repository doubles; Test harness improvements for isolation and reliability; Unit tests for admin infrastructure.

The project is initialized as version 0.11.1 of 'fastapi-agent-blueprint', establishing a FastAPI backend foundation with Python 3.12.9+. Core dependencies include FastAPI 0.115.12, SQLAlchemy 2.0.40, Taskiq 0.12.1 for async tasks, and Pydantic Settings 2.14.2. Optional features are exposed via extras: 'admin' (NiceGUI 3.12.0), 'aws' (Boto3/aioboto3), 'sqs', 'rabbitmq', 'openai', 'pydantic-ai' (slim variants), and 'otel' (OpenTelemetry). The configuration also introduces pyright as the sole type checker, replacing mypy, with strict settings covering src, tests, and harness hooks to ensure zero-error type compliance.

(dependencies) · high confidence

Added empty \_\init\\_.py files to user module structure; Added empty src package initialization.

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• First survey — no prior run to compare against. CAI 68.

• Code Health 89
• Architecture 77
• Maturity 82
• Readiness 51
• Security 89
• Domain Modelling 100

• 300 commits — 190 feature/other, 110 fixes

• (repo) — 94 commits
• src/_core — 47 commits
• (root) — 36 commits
• tests/unit — 28 commits
• .claude/rules — 21 commits
• docs/ai — 17 commits
• src/_apps — 15 commits
• .github/workflows — 6 commits
• .agents/shared — 3 commits
• .claude/hooks — 3 commits
• docs/history — 3 commits
• migrations/versions — 3 commits
• tests/integration — 3 commits
• .antigravity/hooks — 2 commits
• _env/local.env.example — 2 commits
• docs/operations — 2 commits
• examples/web_search_chatbot — 2 commits
• src/admin_identity — 2 commits
• .agents/skills — 1 commit
• .codex/hooks — 1 commit

• fix: Merge pull request #289 from Mr-DooSun/fix/pre-tool-secret-check-path-traversal
• fix: Merge pull request #290 from Mr-DooSun/fix/283-governor-shim-mypy
• fix: Merge pull request #291 from Diyaaa-12/fix/288-latent-test-failures
• fix: Merge pull request #295 from Mr-DooSun/fix/294-bound-chatreply-confidence
• fix: Merge pull request #318 from Mr-DooSun/fix/314-governor-footer-links-entry
• fix: Merge pull request #319 from Mr-DooSun/fix/315-per-tier-webhook-requires-threshold
• fix: Merge pull request #337 from Mr-DooSun/fix/322-bcrypt-event-loop-stall
• fix: Merge pull request #339 from Mr-DooSun/fix/323-exception-translation
• fix: Merge pull request #340 from Mr-DooSun/fix/326-shared-core-container
• fix: Merge pull request #341 from Mr-DooSun/fix/320-gitleaks-discord-webhook
• fix: Merge pull request #342 from Mr-DooSun/fix/324-inline-broker-middleware
• fix: Merge pull request #343 from Mr-DooSun/fix/342-followup-inline-task-runtime
• fix: Merge pull request #344 from Mr-DooSun/fix/322-request-body-size-limit
• fix: Merge pull request #345 from Mr-DooSun/fix/327-notification-provider-graph
• fix: Merge pull request #346 from Mr-DooSun/fix/stale-claims-and-demo-auth
• fix: Merge pull request #347 from Mr-DooSun/fix/332-docker-image-and-compose
• fix: Merge pull request #352 from Mr-DooSun/fix/348-audit-actor-fk-and-silent-swallow
• fix: Merge pull request #354 from Mr-DooSun/fix/328-vector-store-contract
• fix: Merge pull request #355 from Mr-DooSun/fix/329-dynamo-batch-semantics
• fix: Merge pull request #356 from Mr-DooSun/fix/325-base-repository-engine-parity
• …and 280 more

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

Mr-DooSun/fastapi-agent-blueprint was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.