Public Help

whoosh360 Technical Guide

A structured technical reference for the whoosh360 frontend, services, routing model, persistence design, local development setup, ports, and logging conventions.

Help Home User Guide

Overview

whoosh360 is a local-first multi-service application with a React frontend, several Node.js services, and a shared PostgreSQL plus Prisma records foundation. The project is currently in a mixed persistence phase where some domains are already database-backed and others are still transitional.

Architecture

Frontend

The frontend lives in src/ and handles authentication-aware routing, client and admin workspaces, content creation flows, approvals, campaigns, media browsing, analytics, notifications, and admin operations screens.

  • src/main.tsx
  • src/App.tsx
  • src/auth/AuthContext.tsx
  • src/layout/AppShell.tsx
  • src/layout/AdminShell.tsx

Backend Services

  • aim-auth-service on 8788: auth, verification, sessions, onboarding, admin sign-in
  • aim-ops-service on 8789: service health and observability control
  • aim-core-api on 8790: business API for content, settings, media, approvals, previews, and admin controls
  • aim-channel-integration-worker on 8791: channel publishing, token refresh, analytics sync
  • aim-ai-integration-worker on 8792: AI provider execution and fallback routing
  • aim-integration-worker on 8793: background integration and batch processing
  • aim-ai-media-worker on 8794: async media generation scaffold
  • aim-records-engine: PostgreSQL and Prisma foundation on database port 5433

Frontend To Service Relationship

The frontend talks to the local service layer through src/services/mockApi.ts. The filename is historical: it now acts as a hybrid integration layer that issues authenticated requests to running local services (with only a few safe defaults when services are unreachable).

Auth

http://localhost:8788

Ops

http://localhost:8789

Core

http://localhost:8790

AI

http://localhost:8792

Routing Model

Public Routes

  • /signin
  • /signup
  • /verify-email
  • /service-status
  • /admin/signin

Client-Protected Routes

  • /dashboard
  • /post-to-social-media
  • /social-accounts
  • /campaign-approvals
  • /post-approvals
  • /campaigns
  • /published-posts
  • /media-library
  • /analytics
  • /notifications
  • /settings

Redirected Legacy Routes

  • /composer to /post-to-social-media
  • /ai-generator to /post-to-social-media
  • /approvals to /campaign-approvals
  • /calendar to /campaigns
  • /business-profile to /dashboard

Domain Model

The shared types in src/types/index.ts define the core product concepts:

  • Platform: social, messaging, and blog destinations
  • PostType: short-form, long-form, message-based, and editorial content types
  • PostCreationMode: Manual Post, AI Single Post, AI Campaign
  • CampaignStatus: draft through completed, partial, failed, or rejected
  • BusinessProfile: brand and business context
  • CampaignBrief and ManualPostInput: primary creation payloads
  • DemoPreview: reusable preview model
  • PublishedChannelPost: per-channel execution record

Persistence

The project currently uses a mixed persistence approach.

Already PostgreSQL / Prisma Backed

  • business profile
  • media library
  • social accounts
  • admin plans
  • admin global controls
  • platform credentials
  • AI provider configs
  • auth users and sessions

Legacy JSON Backed Or Transitional

  • campaigns
  • approvals
  • published posts
  • analytics
  • notifications
  • some client settings and dashboard support data

Database (DBA)

whoosh360 uses PostgreSQL via Prisma (see hosted-services/aim-records-engine/prisma/schema.prisma) as the source of truth for table names, columns, relations, and enum values.

Connection

  • Database name: aim_records
  • Schema: public
  • Default local port: 5433
  • Connection string: DATABASE_URL (configured in hosted-services/aim-records-engine/.env for local development)
Production note: do not hardcode database credentials in docs. Store credentials in your production secret manager / environment variables and rotate them regularly.

Schema Reference

The full table list (with column names and mappings), enum catalog, and foreign key map is published as a dedicated help page: /help/db-schema.generated.html.

If the schema changes, regenerate that page from the Prisma schema so the DBA reference stays current: python3 scripts/generate-db-schema-help.py.

Sensitive fields: treat these columns as secrets (encrypt at rest + restrict access): admin_controls.smtpPassword, admin_controls.approvalTokenSecret, platform_credentials.fields, social_accounts.connectionDetails, ai_provider_configs.fields, client_settings.emailSmtpPassword, client_settings.wordpressApplicationPassword, media_storage_configs.s3SecretAccessKey.

AI And Content Generation

The main AI workflow centers on src/pages/PostToSocialMediaPage.tsx. It supports manual and AI-assisted creation paths, a large post-type template catalog, reference assets, business-information input mode, and admin-configured provider routing.

Current provider examples configured in admin settings include Pollinations, OpenAI, Anthropic, Google, Mistral, Groq, Stability, Leonardo, Ideogram, and custom providers.

Campaign And Approval Lifecycle

  1. User creates a manual post, AI single post, or AI campaign.
  2. The payload is stored and may generate a preview or schedule future work.
  3. If approvals are required, campaign or post approval items are created.
  4. Approval emails can be delivered through SMTP-configured email flow.
  5. Approved due work is handed to background services for publishing.
  6. Related post records track per-platform execution state.
  7. Failures can be surfaced as failed related posts and retried where supported.
Important behavior: current project behavior treats campaign failure operationally as failed post handling, with retry actions attached to related post records.

Local Development

Basic Frontend

npm install
npm run dev

Full Stack

The repo includes helper scripts:

  • scripts/start-all.sh
  • scripts/stop-all.sh

start-all.sh starts PostgreSQL, all main backend services, and the frontend.

Important Local Ports

  • Frontend: 5173
  • Meta auth helper: 8787
  • Auth service: 8788
  • Ops service: 8789
  • Core API: 8790
  • Channel worker: 8791
  • AI integration worker: 8792
  • Integration worker: 8793
  • AI media worker: 8794
  • PostgreSQL: 5433

Logs And Operations

Runtime Logs

Service runtime logs are stored in logs/, including files like:

  • logs/frontend.log
  • logs/aim-core-api.log
  • logs/aim-auth-service.log
  • logs/aim-ai-integration-worker.log

Development Change Log

Project changes are recorded in DEVLOG.md. At the time this guide was prepared, that was the shared project change log already established in the repository.

Public URL: /help/technical-guide.html