Pattern Stack Knowledge Base

Pattern Stack Knowledge Base

Activation

This skill activates when building applications on the Pattern Stack framework (backend-patterns).

L1 Reference Docs (load when task requires deeper detail)

Task	Reference
Defining models, fields, patterns	patterns-and-fields.md
Building feature services	building-features.md
Building molecules (entities, workflows)	building-molecules.md
Building organisms (facades, routers, CLI)	building-organisms.md
Working with subsystems (cache, jobs, storage, events)	infrastructure-subsystems.md
Writing tests	testing-patterns.md
Project bootstrap	project-bootstrap.md

---

Architecture: Atomic Architecture v2.1

Four layers with unidirectional dependencies (down only):

Organisms  →  Molecules  →  Features  →  Atoms
(interfaces)  (business)    (data CRUD)   (framework)

• Atoms (framework — pattern_stack/atoms/): Domain-agnostic building blocks. Patterns, cache, jobs, security, validators, etc.
• Features (your app): Single-model data services. One feature = one table. NO cross-feature imports.
• Molecules (your app): Compose features into domain entities and workflows. Business logic lives here.
• Organisms (your app): Thin facades + REST/CLI/MCP interfaces. No business logic.

Import Rules (enforced by ArchitectureValidator)

• Atoms → only other atoms (preferably shared/)
• Features → only atoms
• Molecules → features + atoms
• Organisms → molecules + features + atoms
• NEVER: upward imports, cross-feature imports, business logic in organisms

---

Pattern Types

Pattern	Use When	Key Additions
BasePattern	Default for any entity	UUID, timestamps, change tracking, event emission
EventPattern	Has states/transitions	states={}, transition_to(), soft delete, hooks
ActorPattern	Users, orgs, systems	display_name, actor_type, activity tracking
CatalogPattern	Inventory/products	SKU, stock, pricing, categories, weight
CategoricalPattern	Tags, labels, categories	name, slug, color, icon, sort_order
RelationalPattern	Many-to-many joins	entity_a/b, relationship_type, metadata

All patterns: Field() abstraction, Pattern inner class config, change tracking, event emission, ReferenceNumberMixin.

Field Quick Reference

Field(type, required=False, nullable=None, unique=False, index=False,
      default=None, server_default=None, foreign_key=None,
      min=None, max=None, max_length=None, min_length=None, choices=None,
      description=None, ui_type=None, ui_importance="tertiary", ui_label=None)

Types: str, int, bool, float, Decimal, UUID, datetime, date, dict, list, bytes

Service Base Classes

# BaseService gives you: create, get, update, delete, list, exists, count, bulk_*
class MyService(BaseService[MyModel, CreateSchema, UpdateSchema]):
    model = MyModel
    # Only add CUSTOM methods — inherited CRUD just works

# EventService adds: transition_state(db, id, target_state)

---

Infrastructure Subsystems

Subsystem	Backends	Get Singleton	Purpose
Cache	memory, redis, file	get_cache()	TTL-based caching with @cached decorator
Storage	S3/MinIO	get_storage()	Object storage with presigned URLs
Jobs	memory, database	get_job_queue()	Async job queue — no Celery needed
Integrations	—	get_integration_registry()	External system sync (Linear, Jira, etc.)
Events	memory, database	get_event_store()	Persistent event storage + audit trail
Broadcast	memory, redis, noop	get_broadcast()	Real-time client pub/sub

All follow: Protocol → Backend → Factory singleton → configure_X() / get_X() / reset_X()

Jobs Subsystem (Key Discovery)

Built-in async job queue with JobRecord model (6-state lifecycle: pending → running → completed/failed/retrying/dead). DatabaseBackend uses SELECT FOR UPDATE SKIP LOCKED for production multi-worker. No external deps.

queue = get_job_queue()
queue.register_handler("my.job_type", my_handler)
worker = Worker(queue, max_concurrent=3)
await worker.start()

---

Key Imports

# Patterns
from pattern_stack.atoms.patterns import (
    BasePattern, EventPattern, ActorPattern, CatalogPattern,
    CategoricalPattern, RelationalPattern, Field, StatePhase
)
# Services
from pattern_stack.atoms.patterns.services import BaseService
# App Factory
from pattern_stack.atoms.app import create_app
# API
from pattern_stack.atoms.api import APIException, NotFoundException, PaginationParams
# Subsystems
from pattern_stack.atoms.cache import get_cache
from pattern_stack.atoms.storage import get_storage
from pattern_stack.atoms.jobs import get_job_queue, configure_jobs, Worker, JobRecord
from pattern_stack.atoms.integrations import Connection, IntegrationAdapter
from pattern_stack.atoms.shared.events import get_event_store, get_event_bus, EventData
# Testing
from pattern_stack.testing import BaseServiceTest, BaseAPITest
from pattern_stack.testing.factories import BaseFactory, AsyncFactory
# Core
from pattern_stack.core.validator import ArchitectureValidator

---

Decision Guides

"Where does this code go?"

Code Type	Layer	Example
CRUD for ONE model	Feature	UserService, OrderService
Composes multiple services	Molecule entity	HouseholdEntity
Multi-step business process	Molecule workflow	DevelopWorkflow
Permission filtering	Molecule API facade	TransactionAPI
HTTP endpoint	Organism router	router.post("/orders")
CLI command	Organism CLI	@app.command()
Reusable utility	Atom	validators, cache helpers

"Which pattern?"

• Has states/transitions → EventPattern
• Is a user/org/system → ActorPattern
• Has inventory/stock/pricing → CatalogPattern
• Is a tag/category/label → CategoricalPattern
• Is a many-to-many join → RelationalPattern
• None of the above → BasePattern

---

Anti-Patterns

• Business logic in models → put in services/entities
• Cross-feature imports → compose via molecules
• Permission checks in services → put in organism facades
• HTTP concerns in molecules → keep in organisms
• Re-implementing inherited CRUD → BaseService provides it
• Celery for job queues → use built-in Jobs subsystem