Blueprint — Publications

Status: partial (Donor Wall live) · Slug: publications · Kind: ERP · Module #11

1. Module summary

Publications is the institution's outward-voice content management module — website pages, periodical journals, books, electronic media, and the existing public donor wall. Each publication type is a content category with editorial workflow (draft → review → published), version history, and audience-aware distribution (print subscribers, electronic followers, public web). Donor Wall is already live (aayojana.routers.donor_wall) and becomes the first publication-type implementation; Website Content, Journal, Books, and Electronic Media follow the same model. Subscriptions live here (publication ↔ subscriber) and tie to Newsletter for periodical dispatch + Reports for archive exports.

2. Data model

# src/aayojana/publications/models.py
from datetime import datetime, date
from sqlalchemy import (
    JSON, Boolean, Date, DateTime, ForeignKey, Integer, String, Text,
    UniqueConstraint, Index,
)
from sqlalchemy.orm import Mapped, mapped_column, relationship

from aayojana.models.base import AuditMixin, Base, TenantMixin, uuid4_str


class Publication(Base, TenantMixin, AuditMixin):
    """A publication unit — one website page OR one journal issue OR one
    book OR one electronic-media item OR one donor-wall edition."""
    __tablename__ = "publications"
    __table_args__ = (
        UniqueConstraint("tenant_id", "type", "slug",
                         name="uq_publication_tenant_type_slug"),
        Index("ix_publications_type_status", "type", "status"),
    )

    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=uuid4_str)
    type: Mapped[str] = mapped_column(String(32), nullable=False)
    # 'website_page' | 'donor_wall' | 'journal_issue' | 'book' | 'electronic_media' | 'press_release'
    slug: Mapped[str] = mapped_column(String(120), nullable=False)
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    title_sa: Mapped[str | None] = mapped_column(Text, nullable=True)
    # Sanskrit title — VijayaDV PUA preserved (TEXT).
    summary: Mapped[str | None] = mapped_column(Text, nullable=True)
    cover_image_url: Mapped[str | None] = mapped_column(String(500), nullable=True)

    parent_id: Mapped[str | None] = mapped_column(
        String(36), ForeignKey("publications.id"), nullable=True
    )
    # Hierarchy: book ← chapter, journal-volume ← journal-issue, page ← sub-page.

    status: Mapped[str] = mapped_column(String(20), nullable=False, default="draft")
    # 'draft' | 'in_review' | 'published' | 'archived' | 'unpublished'
    published_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
    published_by_user_id: Mapped[int | None] = mapped_column(
        Integer, ForeignKey("users.id"), nullable=True
    )

    # Type-specific fields kept generic via JSON
    metadata_: Mapped[dict | None] = mapped_column("metadata", JSON, nullable=True)
    # Books: {isbn, edition, pages, publisher_name}
    # Journal issues: {volume, issue_number, fy, theme}
    # Electronic media: {duration_seconds, format, mime, transcript_available}
    # Donor wall: {fy, display_until, snapshot_of_count}

    visibility: Mapped[str] = mapped_column(String(20), nullable=False, default="public")
    # 'public' | 'tenant_only' | 'subscribers_only' | 'private'
    seo_description: Mapped[str | None] = mapped_column(Text, nullable=True)


class PublicationVersion(Base, TenantMixin, AuditMixin):
    """Versioned content. Every save is a new row."""
    __tablename__ = "publication_versions"
    __table_args__ = (
        UniqueConstraint("publication_id", "version",
                         name="uq_pubver_publication_version"),
    )

    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=uuid4_str)
    publication_id: Mapped[str] = mapped_column(
        String(36), ForeignKey("publications.id"), nullable=False
    )
    version: Mapped[int] = mapped_column(Integer, nullable=False)
    body_html: Mapped[str | None] = mapped_column(Text, nullable=True)
    body_markdown: Mapped[str | None] = mapped_column(Text, nullable=True)
    body_json: Mapped[dict | None] = mapped_column(JSON, nullable=True)
    # For structured content (donor wall snapshot data, journal articles list).
    editor_user_id: Mapped[int | None] = mapped_column(
        Integer, ForeignKey("users.id"), nullable=True
    )
    published_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)
    is_active: Mapped[bool] = mapped_column(Boolean, default=False, nullable=False)


class PublicationSubscription(Base, TenantMixin, AuditMixin):
    """Subscribers to a publication (mainly Journal, Books, Electronic Media).
    Mailing-list-style subscribers live in Newsletter; this is the SUBSCRIBE-TO-
    A-PUBLICATION-TYPE relation (e.g. "I want every Journal issue mailed")."""
    __tablename__ = "publication_subscriptions"
    __table_args__ = (
        UniqueConstraint("publication_id", "subscriber_kind", "subscriber_key",
                         name="uq_pubsub_pub_subscriber"),
    )

    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=uuid4_str)
    publication_id: Mapped[str] = mapped_column(
        String(36), ForeignKey("publications.id"), nullable=False
    )
    # Or could subscribe to a parent (entire journal series). Resolved by traversal.
    subscriber_kind: Mapped[str] = mapped_column(String(16), nullable=False)
    # 'member' | 'external'
    subscriber_key: Mapped[str] = mapped_column(String(120), nullable=False)
    member_id: Mapped[str | None] = mapped_column(
        String(36), ForeignKey("members.id"), nullable=True
    )
    external_email: Mapped[str | None] = mapped_column(String(255), nullable=True)
    external_name: Mapped[str | None] = mapped_column(String(160), nullable=True)
    postal_address_id: Mapped[str | None] = mapped_column(
        String(36), ForeignKey("addresses.id"), nullable=True
    )

    channel: Mapped[str] = mapped_column(String(16), nullable=False)
    # 'print' | 'electronic'
    paid_until: Mapped[date | None] = mapped_column(Date, nullable=True)
    # Some publications charge for print subscriptions; tracked here, not in Vitta.
    status: Mapped[str] = mapped_column(String(20), nullable=False, default="active")


class MediaAsset(Base, TenantMixin, AuditMixin):
    """Audio, video, image files referenced from publications. Separate from
    Asset Management (which tracks physical assets) — this is for digital
    media files. URL points to GCS / CDN."""
    __tablename__ = "media_assets"
    __table_args__ = (
        Index("ix_media_kind", "kind"),
    )

    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=uuid4_str)
    kind: Mapped[str] = mapped_column(String(16), nullable=False)
    # 'audio' | 'video' | 'image' | 'pdf' | 'document'
    title: Mapped[str] = mapped_column(String(255), nullable=False)
    description: Mapped[str | None] = mapped_column(Text, nullable=True)
    storage_url: Mapped[str] = mapped_column(String(500), nullable=False)
    # GCS path or external CDN URL.
    mime_type: Mapped[str | None] = mapped_column(String(80), nullable=True)
    size_bytes: Mapped[int | None] = mapped_column(Integer, nullable=True)
    duration_seconds: Mapped[int | None] = mapped_column(Integer, nullable=True)
    transcript: Mapped[str | None] = mapped_column(Text, nullable=True)
    # Sanskrit transcripts preserved verbatim.
    rights: Mapped[str | None] = mapped_column(String(80), nullable=True)
    # 'cc-by' | 'all-rights-reserved' | 'public-domain'
    captured_at: Mapped[datetime | None] = mapped_column(DateTime, nullable=True)


class PublicationMediaLink(Base, TenantMixin, AuditMixin):
    """N:M between Publication and MediaAsset."""
    __tablename__ = "publication_media_links"
    __table_args__ = (
        UniqueConstraint("publication_id", "media_id", name="uq_pubmedia"),
    )
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    publication_id: Mapped[str] = mapped_column(
        String(36), ForeignKey("publications.id"), nullable=False
    )
    media_id: Mapped[str] = mapped_column(
        String(36), ForeignKey("media_assets.id"), nullable=False
    )
    role: Mapped[str | None] = mapped_column(String(40), nullable=True)
    # 'cover' | 'inline' | 'attachment' | 'transcript'

3. Reuse map

4. API surface

5. Service layer

# src/aayojana/publications/service.py

async def create_publication(
    db, *, tenant_id, type, slug, title, title_sa=None, parent_id=None,
    metadata=None, visibility="public",
) -> "Publication": ...

async def save_version(
    db, *, tenant_id, publication_id,
    body_html=None, body_markdown=None, body_json=None,
    editor_user_id=None,
) -> "PublicationVersion": ...

async def publish(
    db, *, tenant_id, publication_id, version_id=None, user_id=None,
) -> "Publication":
    """Activates the given version (or latest if None). For periodical types,
    optionally triggers comms.send_to_segment to subscribers."""

async def subscribe(
    db, *, tenant_id, publication_id, member_id=None,
    external_email=None, external_name=None,
    channel="electronic", postal_address_id=None,
) -> "PublicationSubscription": ...

async def upload_media_asset(
    db, *, tenant_id, kind, title, storage_url, mime_type=None,
    size_bytes=None, transcript=None,
) -> "MediaAsset": ...

async def attach_media(
    db, *, tenant_id, publication_id, media_id, role="inline",
) -> None: ...

6. UI / Templates

src/aayojana/templates/publications/. Reuses existing donor_wall/display.html relocated under this module.

7. Migration plan

8. Cross-module dependencies

• Comms — periodical issue dispatch via send_to_segment for journal subscribers.
• Newsletter — Publications subscribers may auto-populate Newsletter mailing lists (e.g. journal print subscribers segment).
• Reports — publications_donor_wall_analytics, publications_journal_subscribers, publications_media_engagement registered.
• Members Suite — member-typed subscribers FK back to members.id.
• Asset Management (Agent 4) — physical book inventory cross-linked via Publication.metadata.asset_inventory_id.
• Audit — publish/unpublish events recorded for Books and Press Releases (legal-weight publications).

9. Implementation phases

Phase A — Migrate donor wall + website pages (1 week): 1. Land migration 0033. 2. Migrate existing donor wall logic into Publication-backed flow. 3. Implement website-page CMS.

Phase B — Journal + Subscriptions (2 weeks): 4. Journal issue editor. 5. Subscribers admin. 6. Integration with Comms for issue dispatch. 7. Public journal archive.

Phase C — Books + Electronic Media (2 weeks): 8. Book editor with chapter tree. 9. Media asset library + upload-to-GCS signed URL flow. 10. Audio/video player with transcript. 11. Public catalogs.

10. Open questions

1. Editor tooling — same TipTap as Newsletter, or different per type? Recommendation: Same TipTap base; type-specific extensions (book chapter outline, journal article-list).
2. Media storage — GCS direct vs CDN (Cloudflare R2)? Recommendation: GCS for v1 (already used for reports outputs); CDN swap if media traffic grows.
3. ISBN allocation — manual entry, or integrate with national-ISBN-agency? Recommendation: Manual for India (ISBN-issued by Raja Rammohun Roy National Agency, not API-ised).
4. Public URL structure — per-tenant subdomain vs path-based? Rec: Path-based on tenant's primary domain (https://{tenant.domain}/publications/...).
5. Journal pricing/payment — free for Indian subscribers, paid for foreign? Recommendation: Out of scope for Publications; if needed, integrate with existing payment flow at subscribe time and store paid_until.
6. Donor wall PII — strict opt-in display, or default-show? Recommendation: Honour existing members.hide_name / hide_amount flags (already DISA convention).
7. Transcripts for electronic media — required, or optional? Rec: Optional, but Sanskrit recordings strongly encouraged to ship transcripts (accessibility + searchability).
8. Press releases — separate type, or sub-type of website-page? Rec: Separate type (type='press_release') so Outreach Module's media-coverage tracker can FK back to specific releases.