Tech debt cleanup: fix session.py, remove stale references, update docs
- db/session.py: fix indentation (2→4 space), pool_size=0 (unlimited), remove "ned to look at this" typo - Remove glue.models from alembic env.py import list - Update shared __init__.py, menu_item.py docstring, calendar_impl.py, handlers/__init__.py to remove glue terminology - Remove federation_handlers.py tombstone file - Remove TODO comments (replace with explanatory comments) - Rewrite README.md to reflect current architecture - Update anchoring.py TODO to plain comment Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
giles
72
README.md
72
README.md
@@ -1,6 +1,6 @@
|
||||
# Shared
|
||||
|
||||
Shared infrastructure, models, templates, and configuration used by all four Rose Ash microservices (blog, market, cart, events). Included as a git submodule in each app.
|
||||
Shared infrastructure, models, contracts, services, and templates used by all five Rose Ash microservices (blog, market, cart, events, federation). Included as a git submodule in each app.
|
||||
|
||||
## Structure
|
||||
|
||||
@@ -8,20 +8,41 @@ Shared infrastructure, models, templates, and configuration used by all four Ros
|
||||
shared/
|
||||
db/
|
||||
base.py # SQLAlchemy declarative Base
|
||||
session.py # Async session factory (get_session)
|
||||
models/ # Shared domain models
|
||||
session.py # Async session factory (get_session, register_db)
|
||||
models/ # Canonical domain models
|
||||
user.py # User
|
||||
magic_link.py # MagicLink (auth tokens)
|
||||
domain_event.py # DomainEvent (transactional outbox)
|
||||
kv.py # KeyValue (key-value store)
|
||||
menu_item.py # MenuItem
|
||||
menu_item.py # MenuItem (deprecated — use MenuNode)
|
||||
menu_node.py # MenuNode (navigation tree)
|
||||
container_relation.py # ContainerRelation (parent-child content)
|
||||
ghost_membership_entities.py # GhostNewsletter, UserNewsletter
|
||||
federation.py # ActorProfile, APActivity, APFollower, APFollowing,
|
||||
# RemoteActor, APRemotePost, APLocalPost,
|
||||
# APInteraction, APNotification, APAnchor, IPFSPin
|
||||
contracts/
|
||||
dtos.py # Frozen dataclasses for cross-domain data transfer
|
||||
protocols.py # Service protocols (Blog, Calendar, Market, Cart, Federation)
|
||||
widgets.py # Widget types (NavWidget, CardWidget, AccountPageWidget)
|
||||
services/
|
||||
registry.py # Typed singleton: services.blog, .calendar, .market, .cart, .federation
|
||||
blog_impl.py # SqlBlogService
|
||||
calendar_impl.py # SqlCalendarService
|
||||
market_impl.py # SqlMarketService
|
||||
cart_impl.py # SqlCartService
|
||||
federation_impl.py # SqlFederationService
|
||||
federation_publish.py # try_publish() — inline AP publication helper
|
||||
stubs.py # No-op stubs for absent domains
|
||||
navigation.py # get_navigation_tree()
|
||||
relationships.py # attach_child, get_children, detach_child
|
||||
widget_registry.py # Widget registry singleton
|
||||
widgets/ # Per-domain widget registration
|
||||
infrastructure/
|
||||
factory.py # create_base_app() — Quart app factory
|
||||
cart_identity.py # current_cart_identity() (user_id or session_id)
|
||||
cart_loader.py # Cart data loader for context processors
|
||||
context.py # Jinja2 context processors
|
||||
internal_api.py # Inter-app HTTP client (get/post via httpx)
|
||||
jinja_setup.py # Jinja2 template environment setup
|
||||
urls.py # URL helpers (coop_url, market_url, etc.)
|
||||
user_loader.py # Load current user from session
|
||||
@@ -29,32 +50,36 @@ shared/
|
||||
events/
|
||||
bus.py # emit_event(), register_handler()
|
||||
processor.py # EventProcessor (polls domain_events, runs handlers)
|
||||
browser/app/
|
||||
csrf.py # CSRF protection
|
||||
errors.py # Error handlers
|
||||
middleware.py # Request/response middleware
|
||||
redis_cacher.py # Tag-based Redis page caching
|
||||
authz.py # Authorization helpers
|
||||
filters/ # Jinja2 template filters (currency, truncate, etc.)
|
||||
utils/ # HTMX helpers, UTC time, parsing
|
||||
payments/sumup.py # SumUp checkout API integration
|
||||
browser/templates/ # ~300 Jinja2 templates shared across all apps
|
||||
config.py # YAML config loader
|
||||
handlers/ # Shared event handlers
|
||||
container_handlers.py # Navigation rebuild on attach/detach
|
||||
login_handlers.py # Cart/entry adoption on login
|
||||
order_handlers.py # Order lifecycle events
|
||||
ap_delivery_handler.py # AP activity delivery to follower inboxes
|
||||
utils/
|
||||
__init__.py
|
||||
calendar_helpers.py # Calendar period/entry utilities
|
||||
http_signatures.py # RSA keypair generation, HTTP signature signing/verification
|
||||
ipfs_client.py # Async IPFS client (add_bytes, add_json, pin_cid)
|
||||
anchoring.py # Merkle trees + OpenTimestamps Bitcoin anchoring
|
||||
webfinger.py # WebFinger actor resolution
|
||||
browser/
|
||||
app/ # Middleware, CSRF, errors, Redis caching, authz, filters
|
||||
templates/ # ~300 Jinja2 templates shared across all apps
|
||||
containers.py # ContainerType, container_filter, content_filter helpers
|
||||
config.py # YAML config loader
|
||||
log_config/setup.py # Logging configuration (JSON formatter)
|
||||
utils.py # host_url and other shared utilities
|
||||
static/ # Shared static assets (CSS, JS, images, FontAwesome)
|
||||
editor/ # Koenig (Ghost) rich text editor build
|
||||
alembic/ # Database migrations (25 versions)
|
||||
env.py # Imports models from all apps (with try/except guards)
|
||||
versions/ # Migration files — single head: j0h8e4f6g7
|
||||
alembic/ # Database migrations
|
||||
```
|
||||
|
||||
## Key Patterns
|
||||
|
||||
- **App factory:** All apps call `create_base_app()` which sets up DB sessions, CSRF, error handling, event processing, logging, and the glue handler registry.
|
||||
- **App factory:** All apps call `create_base_app()` which sets up DB sessions, CSRF, error handling, event processing, logging, widget registration, and domain service wiring.
|
||||
- **Service contracts:** Cross-domain communication via typed Protocols + frozen DTO dataclasses. Apps call `services.calendar.method()`, never import models from other domains.
|
||||
- **Service registry:** Typed singleton (`services.blog`, `.calendar`, `.market`, `.cart`, `.federation`). Apps wire their own domain + stubs for others via `register_domain_services()`.
|
||||
- **Event bus:** `emit_event()` writes to `domain_events` table in the caller's transaction. `EventProcessor` polls and dispatches to registered handlers.
|
||||
- **Inter-app HTTP:** `internal_api.get/post("cart", "/internal/cart/summary")` for cross-app reads. URLs resolved from `app-config.yaml`.
|
||||
- **Widget registry:** Domain services register widgets (nav, card, account); templates consume via `widgets.container_nav`, `widgets.container_cards`.
|
||||
- **Cart identity:** `current_cart_identity()` returns `{"user_id": int|None, "session_id": str|None}` from the request session.
|
||||
|
||||
## Alembic Migrations
|
||||
@@ -62,8 +87,5 @@ shared/
|
||||
All apps share one PostgreSQL database. Migrations are managed here and run from the blog app's entrypoint (other apps skip migrations on startup).
|
||||
|
||||
```bash
|
||||
# From any app directory (shared/ must be on sys.path)
|
||||
alembic -c shared/alembic.ini upgrade head
|
||||
```
|
||||
|
||||
Current head: `j0h8e4f6g7` (drop cross-domain FK constraints).
|
||||
|
||||
Reference in New Issue
Block a user