PublyApp

What is PublyApp?

PublyApp is a full-stack SaaS foundation for teams operating across multiple organizations and projects. The repository combines a .NET 10 API, a React 19 frontend built with TanStack Start, PostgreSQL, background jobs, database migrations, and a TypeScript client generated from the API's OpenAPI contract.

The platform has three distinct operating scopes:

Scope	Purpose
Staff	Platform-wide administration and support across tenants.
Tenant	Organization-level users, settings, and operations.
Project	A workspace boundary inside a tenant.

Staff and tenant/project accounts are mutually exclusive. This keeps the platform-administration boundary separate from tenant data and permissions.

What ships today

• Multi-tenant request handling with explicit tenant isolation.
• Session authentication and route-level permission enforcement.
• Staff, tenant, and project account boundaries.
• User, role, permission, and invitation workflows.
• Post drafting, scheduling, publish-now actions, and publication history.
• Social-account connections and a Bluesky publishing provider.
• Audit logs and system notices for observable administration.
• RFC 7807 error contracts and an OpenAPI-generated Kiota client.
• A deployable API, background worker, database migrator, and frontend.

Product direction

PublyApp already carries the core post and publishing pipeline. The product direction is to turn it into a complete multi-network workspace, with richer calendar, queue, planning, and review experiences. Those end-to-end product surfaces remain active development areas; partial workflows are not presented as complete.

Quick start

Prerequisites

• Node.js 24 or newer
• pnpm 10.13.1
• .NET SDK 10
• Docker
• just

On Windows, the justfile requires PowerShell 7 (pwsh).

Start the full local stack

cp .env.example .env.development
just dev

just dev stays attached and runs the whole stack: it applies pending migrations, then starts persistent PostgreSQL (host port 5454), the API (5000), the worker, and the frontend (5050). just dev <pr|issue|branch> runs the same stack from the matching worktree, creating it when missing. Branches created before #2305 must be updated with develop first.

Service	Local address
Frontend	http://localhost:5050
API	http://localhost:5000
API reference (Scalar)	http://localhost:5000/scalar/v1
PostgreSQL	localhost:5454

Do not start just dev-api alongside just dev; the AppHost already owns port 5000. For the single-piece recipes and environment rules, read the development commands in AGENTS.md.

Architecture at a glance

flowchart LR
    Browser["apps/front<br/>React 19 · TanStack Start"]
    Client["packages/client-ts<br/>generated by Kiota"]
    API["apps/api<br/>.NET 10 Minimal API"]
    Handlers["handlers · services"]
    DB[("PostgreSQL 18")]
    Worker["worker<br/>same API image"]
    Migrator["one-shot migrator"]

    Browser --> Client
    Client -->|X-Session-Token · X-Tenant-Id| API
    API --> Handlers --> DB
    Worker --> DB
    Migrator --> DB
    API -. OpenAPI .-> Client

The backend uses domain-first vertical slices: endpoints map routes and permissions, handlers orchestrate an operation, and domain services own business logic and data access. Authenticated frontend data stays client-side and flows through TanStack Query and the generated API client.

apps/
├── api/          # API, worker runtime, and migrator source
└── front/        # shipped TanStack Start frontend
packages/
├── client-ts/    # generated API client; never edit by hand
├── shared-ts/    # shared validation, types, and i18n
├── lint-ts/      # custom TypeScript lint rules
├── lint-cs/      # custom Roslyn analyzers
└── scripts-cs/   # .NET code-generation tools

Read the focused guides for the full rules:

• Backend module structure
• API route design
• Frontend architecture and commands
• Frontend conventions
• Architecture details

API contract workflow

The TypeScript client is generated from the backend's OpenAPI document. After changing an endpoint or wire contract, regenerate and type-check it:

just build-api
just generate-client
pnpm --filter front typecheck

Never hand-edit packages/client-ts; regeneration replaces its contents.

Development and quality

The repository uses just for its supported workflows. just --list is the full command reference; these are the common entry points:

Command	Purpose
just dev	Run the complete local stack.
just build-api	Build the API and emit OpenAPI.
pnpm --filter front build	Build the shipped frontend.
just test-api	Run API integration tests with Testcontainers.
pnpm --filter front test	Run frontend tests and their existing guards.
just lint && just format	Apply lint and formatting fixes.
just ci	Run the local pre-push gate, including the API suite.
just ci-full	Add both end-to-end suites to the pre-push gate.

This is the beginning of the README. Read the rest at the original. Read the full README ↗