feat: add standards wiki, MCP registry, and app template

templates/app/infra/adapters/service.py

@@ -0,0 +1,128 @@
+"""# Summary
+
+Generic CRUD service adaptor over a Mongo repository.
+
+Bridge pydantic models and mongo-ops documents, exposing create, read, update,
+patch, delete, and search operations for every domain that needs them.
+"""
+from typing import Generic, Type, TypeVar
+
+from infra.db.repos import mongo
+
+from pydantic import BaseModel
+from mongo_ops import BaseDocument
+from mongo_ops.models import PyObjectId
+
+Model = TypeVar("Model", bound=BaseModel)
+Schema = TypeVar("Schema", bound=BaseDocument)
+
+
+class CrudsServiceAdaptor(Generic[Model, Schema]):
+    """Adapt a generic Mongo repository to a model/schema CRUD service.
+
+    Attributes:
+        repo (mongo.BaseRepository): Repository backing all CRUD operations.
+        model (Type[Model]): Pydantic model type handled by this service.
+        schema (Type[Schema]): Document schema type persisted by the repository.
+    """
+
+    repo: mongo.BaseRepository
+    model: Type[Model]
+    schema: Type[Schema]
+
+    def __init__(self, *, repo=None):
+        """Initialize the adaptor with a backing repository.
+
+        Args:
+            repo (mongo.BaseRepository): Repository used for all operations.
+        """
+        self.repo = repo
+
+    @staticmethod
+    def model_to_dict(model_obj: Model) -> dict:
+        """Serialize a model into a sparse dictionary.
+
+        Args:
+            model_obj (Model): Model instance to serialize.
+
+        Returns:
+            dict: Fields that are set and not ``None``.
+        """
+        return model_obj.model_dump(exclude_unset=True, exclude_none=True)
+
+    async def create(self, data: Model | dict) -> Schema:
+        """Create a document from a model or raw mapping.
+
+        Args:
+            data (Model | dict): Model instance or field mapping to persist.
+
+        Returns:
+            Schema: Persisted document.
+        """
+        if isinstance(data, dict):
+            data = self.schema(**data)
+        return await self.repo.create(data)
+
+    async def read(self, id: PyObjectId) -> Schema | None:
+        """Read a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+
+        Returns:
+            Schema | None: Matching document, or ``None`` when absent.
+        """
+        return await self.repo.get_by_id(id)
+
+    async def update(self, id: PyObjectId, data: Model | dict) -> Schema | None:
+        """Replace a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+            data (Model | dict): Replacement model or field mapping.
+
+        Returns:
+            Schema | None: Updated document, or ``None`` when absent.
+        """
+        return await self.repo.update(
+            id,
+            data if isinstance(data, dict) else self.model_to_dict(data),
+        )
+
+    async def patch(self, id: PyObjectId, data: dict) -> Schema | None:
+        """Partially update a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+            data (dict): Fields to patch.
+
+        Returns:
+            Schema | None: Updated document, or ``None`` when absent.
+        """
+        return await self.repo.patch(id, data)
+
+    async def delete(self, id: PyObjectId) -> bool:
+        """Delete a document by primary key.
+
+        Args:
+            id (PyObjectId): Document identifier.
+
+        Returns:
+            bool: ``True`` when a document was deleted.
+        """
+        return await self.repo.delete(id)
+
+    async def search(self, filter: dict | None = None, *args, **kwargs) -> list[Schema]:
+        """List documents matching an optional filter.
+
+        Args:
+            filter (dict | None): Query filter passed to the repository.
+
+        Returns:
+            list[Schema]: Matching documents.
+
+        Notes:
+            Extra positional and keyword arguments are forwarded to the
+            repository.
+        """
+        return await self.repo.get_many(filter=filter, *args, **kwargs)

templates/app/infra/db/repos/mongo.py

@@ -0,0 +1,42 @@
+"""# Summary
+
+Generic MongoDB CRUD repo — single implementation for all domains.
+
+Select a concrete mongo-ops repository (base, cached, or populating) from the
+options supplied to the factory.
+"""
+from typing import List, Optional, Type
+
+from mongo_ops import BaseRepository, CachedBaseRepository, PopulatingRepository
+from mongo_ops.cache import CacheBackend, CacheConfig
+from mongo_ops.models import BaseDocument
+from mongo_ops.populate import PopulationEngine, PopulateRule
+
+
+def _repo_factory(
+    collection: str,
+    db_model: Type[BaseDocument],
+    cache_backend: Optional[CacheBackend] = None,
+    cache_config: Optional[CacheConfig] = None,
+    engine: Optional[PopulationEngine] = None,
+    populate_rules: Optional[List[PopulateRule]] = None,
+) -> BaseRepository:
+    """Build the appropriate mongo-ops repository.
+
+    Args:
+        collection (str): Collection name to operate on.
+        db_model (Type[BaseDocument]): Document model bound to the collection.
+        cache_backend (Optional[CacheBackend]): Cache backend enabling cached reads.
+        cache_config (Optional[CacheConfig]): Cache configuration for the backend.
+        engine (Optional[PopulationEngine]): Population engine for reference expansion.
+        populate_rules (Optional[List[PopulateRule]]): Rules applied by the engine.
+
+    Returns:
+        BaseRepository: Repository instance matching the supplied options.
+    """
+    if engine and populate_rules is not None:
+        return PopulatingRepository(collection, db_model, engine, populate_rules)
+    elif cache_backend is not None:
+        return CachedBaseRepository(collection, db_model, cache_backend, cache_config)
+    else:
+        return BaseRepository(collection, db_model)

templates/app/infra/db/setup.py

@@ -0,0 +1,23 @@
+"""# Summary
+
+Database setup — connection lifecycle only. No domain imports.
+
+Connect and disconnect the shared Mongo connection manager at application
+startup and shutdown.
+"""
+from mongo_ops import MongoConnectionManager
+
+
+async def setup_database(uri: str, db_name: str):
+    """Connect the shared Mongo connection manager.
+
+    Args:
+        uri (str): Mongo connection URI.
+        db_name (str): Target database name.
+    """
+    await MongoConnectionManager.connect(uri=uri, db_name=db_name)
+
+
+async def shutdown_database():
+    """Disconnect the shared Mongo connection manager."""
+    await MongoConnectionManager.disconnect()