Taackk
Internalv2.0 · August 2026

Developer Resources

API reference, database schema, compliance architecture, IAM, analytics, and integration guides for the Taackk platform. This page is restricted to authorised personnel only.

Data Handling Notice

This documentation page contains architectural and configuration information classified as internal. It must not be shared externally, cached by search engines, or included in public-facing assets. Access is restricted to authorised engineering and compliance personnel. All information on this page is subject to Taackk's internal data classification policy.

API Reference

REST API Endpoints

All endpoints are registered in src/server/entry.ts. Backend handlers live in src/server/api/. Auth middleware is noted per endpoint.

POST/api/contact/:formNameNone

Description

Submit a contact or intake form. Supported formName values: business-onboarding, leader-application.

Body / Params

Structured fields in conversation.data; free-text in messages_attributes[0].body

Response

200 OK — { success: true }
GET/api/healthNone

Description

Server health check. Returns 200 when the API is reachable.

Body / Params

—

Response

200 OK — { status: "ok" }
POST/api/stripe/create-checkout-sessionNone (pre-auth flow)

Description

Create a Stripe Checkout session for a leader subscription tier.

Body / Params

{ priceId: string, tier: "tier1" | "tier2" | "tier3", successUrl: string, cancelUrl: string }

Response

200 OK — { sessionId: string, url: string }
GET/api/stripe/session/:sessionIdNone (session ID is the credential)

Description

Retrieve a Stripe Checkout session by ID. Used on the success page to confirm payment.

Body / Params

—

Response

200 OK — Stripe Session object
POST/api/admin/gdpr-anonymizerequireAdminAuth (super_admin)

Description

GDPR Article 17 Right to Erasure. Anonymises PII across users, executive_profiles, and historic audit log payloads. Records a final ANONYMIZE compliance event.

Body / Params

{ userId: string (UUID), adminActorId: string (UUID) }

Response

200 OK — { success: true, userId, logsScrubbed: number }
GET/api/admin/audit-queryrequireAdminAuth

Description

Paginated read-only audit log inspection for compliance reporting.

Body / Params

?tableName=&actorId=&recordId=&action=&limit=50&offset=0

Response

200 OK — { rows: AuditLog[], count: number, limit, offset }
GET/api/admin/audit-logrequireAdminAuth

Description

Feature-flag audit log (DB-backed). Filterable by employeeId, action, scope, and date range.

Body / Params

?employeeId=&action=&scope=&from=&to=&limit=50&offset=0

Response

200 OK — { rows: FeatureFlagAuditLog[], count: number }
GET/api/admin/incidentsrequireAdminAuth (super_admin)

Description

List all data breach / incident response records. Restricted to super_admin role.

Body / Params

?status=&severity=&limit=50&offset=0

Response

200 OK — { incidents: Incident[], count: number }
POST/api/admin/incidentsrequireAdminAuth (super_admin)

Description

Create a new incident record. Starts the GDPR 72-hour DPA notification countdown.

Body / Params

{ title, severity, description, affectedUserCount, dataCategories }

Response

201 Created — { incident: Incident }
PATCH/api/admin/incidents/:incidentIdrequireAdminAuth (super_admin)

Description

Update incident status, severity, or resolution notes.

Body / Params

Partial Incident fields

Response

200 OK — { incident: Incident }
GET/api/admin/security-scanrequireAdminAuth (super_admin)

Description

Retrieve historical security scan reports from DB. Each report includes severity counts and full output log.

Body / Params

—

Response

200 OK — { reports: SecurityScanReport[] }
POST/api/admin/security-scanrequireAdminAuth (super_admin)

Description

Trigger a new security scan. Creates a running record, executes the scan, then updates with results.

Body / Params

{ type: "full" | "quick" | "pentest" }

Response

200 OK — { report: SecurityScanReport }
GET/api/admin/email-templatesrequireAdminAuth

Description

List all email templates from DB. Seeded from defaults on first access.

Body / Params

—

Response

200 OK — { templates: EmailTemplate[] }
PATCH/api/admin/email-templates/:keyrequireAdminAuth

Description

Update subject and HTML body of an email template by key.

Body / Params

{ subject?: string, html?: string }

Response

200 OK — { template: EmailTemplate }
GET/api/business/analytics/entitlementrequireBusinessAuth

Description

Returns the authenticated business organisation's subscription tier and enabled feature flags.

Body / Params

—

Response

200 OK — { tier: string, features: Record<string, boolean> }
GET/api/leader/analytics/*requireLeaderAuth

Description

Leader analytics suite — 10 endpoints covering KPIs, engagement, performance, AI report generation, and export (CSV/XLSX/JSON/PDF by tier).

Body / Params

Varies by endpoint; see src/server/api/leader/analytics/

Response

200 OK — varies
Database

MySQL Schema (Drizzle ORM)

11 tables with SOC 2 / GDPR-compliant soft deletes on all core entities. Schema defined in src/server/db/schema.ts. Migrations in scripts/migrations/.

users
GDPR Art. 17 — anonymizable

Core identity table. Stores credentials, subscription tier, Stripe customer ID, and soft-delete columns. Contains PII — subject to GDPR Article 17 anonymization.

id (UUID PK)emailrole (leader|business|admin)subscription_tierstripe_customer_iddeleted_atdeleted_bydeletion_reason
executive_profiles
GDPR Art. 17 — anonymizable

Leader profiles with sectors, functions, engagement types, availability, and verification status. Contains PII — subject to GDPR Article 17 anonymization.

id (UUID PK)user_id (FK → users)headlinebiosectors (JSON)functions (JSON)engagement_types (JSON)verification_statusdeleted_at
business_profiles
Soft-delete required

Company profiles capturing industry, size, leader needs, and engagement budget.

id (UUID PK)user_id (FK → users)company_nameindustryleader_needs (JSON)engagement_budgetdeleted_at
profile_verifications
Soft-delete required

Verification workflow state machine for both executive and business profiles.

id (UUID PK)profile_type (EXECUTIVE|BUSINESS)profile_idstatus (UNVERIFIED→APPROVED|REJECTED|REVOKED)verifier_idrejection_reasondeleted_at
audit_activity_logs
Append-only — INSERT/SELECT only

Immutable append-only compliance log. Application role may only INSERT/SELECT — never UPDATE or DELETE. Satisfies SOC 2 CC6.8 and ISO 27001 A.12.4.

id (BIGINT autoincrement PK)table_namerecord_idaction (INSERT|UPDATE|DELETE|SOFT_DELETE|RESTORE|ANONYMIZE)old_data (JSON — PII redacted on ANONYMIZE)new_data (JSON — PII redacted on ANONYMIZE)changed_fields (JSON)actor_idactor_roleclient_ipcorrelation_idcreated_at
leader_applications
Soft-delete required

Captures /apply wizard submissions across all 4 steps. Linked to Stripe session on tier selection.

id (UUID PK)emailselected_tierstripe_session_idstatus (pending|approved|rejected)deleted_at
business_onboarding_submissions
Soft-delete required

Captures /onboarding wizard submissions across all 4 steps.

id (UUID PK)contact_emailcompany_nameleader_needs (JSON)selected_planstatus (new|contacted|converted|closed)deleted_at
feature_flag_audit_log
SOC 2 CC6.1 — change management

DB-backed audit trail for all feature flag changes. Replaces prior in-memory array. Satisfies SOC 2 CC6.1 change management controls.

id (UUID PK)timestampemployeeIdemployeeNameactiontargetScopetargetIdcomponentNamepreviousState (JSON)newState (JSON)
email_templates
No PII stored

Stores all transactional email templates. Seeded from defaults on first access. Editable via admin UI at /admin/templates.

key (VARCHAR PK)labelsubjecthtmlupdatedAt
security_scan_reports
Restricted to super_admin

Persistent security scan history. Each run creates a running record then updates with full report JSON and severity counts.

id (UUID PK)type (full|quick|pentest)status (running|complete|failed)reportJson (JSON)severityCounts (JSON)outputLog (TEXT)createdAtcompletedAt
data_breach_incidents
GDPR Art. 33 — 72h DPA notification

Incident response records for data breaches. Tracks GDPR 72-hour DPA notification countdown and affected user scope.

id (UUID PK)titleseverity (low|medium|high|critical)status (open|investigating|contained|resolved)affectedUserCountdataCategories (JSON)detectedAtcontainedAtresolvedAtdpaNotifiedAt

Soft Delete Rule

Hard DELETE statements on core tables are prohibited. All deletions must set deleted_at, deleted_by, and deletion_reason. Application queries must always filter WHERE deleted_at IS NULL.

Compliance

Audit & Compliance Architecture

SOC 2 Type II, GDPR, and ISO 27001 controls implemented across the platform. Audit middleware in src/server/lib/audit.ts.

Audit Context Middleware

Every mutating API handler calls buildAuditContext(req) to extract actor identity, then passes the context to writeAuditLog().

import { buildAuditContext, writeAuditLog }
from '../lib/audit.js';

// In your handler:
const ctx = buildAuditContext(req);
await writeAuditLog(ctx, {
tableName: 'users',
recordId, action: 'UPDATE',
oldData, newData, changedFields,
});

GDPR Article 17 Anonymization

PII is anonymised in-place across users, executive_profiles, and historic audit_activity_logs JSON payloads. Audit rows are never deleted — structural integrity is preserved. A final ANONYMIZE event is appended to the audit log.

POST /api/admin/gdpr-anonymize

{
"userId": "<uuid>",
"adminActorId": "<uuid>"
}

Audit Action Types

INSERT

New record created

UPDATE

Record fields modified

SOFT_DELETE

deleted_at set — record hidden from application queries

RESTORE

deleted_at cleared — record made active again

DELETE

Hard delete — prohibited on core tables; logged if it occurs

ANONYMIZE

GDPR Article 17 PII erasure — PII fields overwritten, audit row preserved

SOC 2CC6.1

Actor attribution via JWT sub on every mutating request; feature-flag changes logged to DB

SOC 2CC6.2

Role-based access control with 4 admin roles and 14+ granular permissions

SOC 2CC6.8 / CC7.2

Append-only audit log — application role has INSERT/SELECT only, never UPDATE/DELETE

GDPRArt. 5(1)(f)

Full JSON payload snapshots on all mutating operations; PII redacted on ANONYMIZE

GDPRArt. 17

Right to Erasure — PII anonymised in-place; audit row structural integrity preserved

GDPRArt. 33

Data breach incidents tracked with 72-hour DPA notification countdown

ISO 27001A.9.4

Brute-force defence and account lockout on authentication endpoints

ISO 27001A.10.1

AES-256-GCM field-level encryption for sensitive data at rest

ISO 27001A.12.4

NDJSON structured logger with PII redaction; all logs include correlation_id

ISO 27001A.16.1

Incident response workflow with severity classification and DPA notification tracking

IAM

Identity & Access Management

Identity and Access Management (IAM) system covering employee roles, team assignments, policy enforcement, break-glass access, and customer impersonation with dual-control approval. Migrations 0015–0016.

IAM Database Tables

  • iam_employees — admin staff with roles and MFA status
  • iam_teams — organisational groupings
  • iam_policies — named permission sets
  • iam_role_assignments — employee ↔ policy bindings
  • iam_break_glass_requests — emergency access with dual-control approval
  • impersonation_tickets — customer impersonation with step-up MFA
  • leader_impersonation_sessions — scoped JWT (15-min max) with red/black hazard banner
  • iam_audit_log — all IAM mutations logged

Compliance Requirements

  • Dual-control approval required for all customer impersonation sessions
  • Break-glass requests require two approvers from separate IAM teams
  • Leader impersonation tokens are scoped JWTs with 15-minute maximum TTL
  • All IAM mutations are written to iam_audit_log — append-only
  • Step-up MFA required before impersonation ticket launch
viewer

Read-only access to admin portal

operator

Can manage applications and customers

admin

Full admin portal access

super_admin

Security scan, incidents, IAM management, impersonation approval

Payments

Stripe Configuration

Platform-managed Stripe integration (AU). Secrets are provisioned automatically — do not add STRIPE_SECRET_KEY or STRIPE_PUBLISHABLE_KEY manually. Account and price IDs are stored in platform secrets, not in this document.

ProviderStripe (AU)
CurrencyAUD
Associate — Tier 1AUD $149/mo
Pro — Tier 2AUD $349/mo
Elite — Tier 3AUD $699/mo
SecretsSTRIPE_SECRET_KEY, STRIPE_PUBLISHABLE_KEY (platform-managed — do not add manually)

Checkout Flow

The /apply wizard POSTs to POST /api/stripe/create-checkout-session on step 4 tier selection, then redirects to the Stripe-hosted checkout URL. On success, the browser lands on /checkout/success?session_id=… which calls GET /api/stripe/session/:sessionId to confirm payment.

Security Note

Stripe account identifiers, price IDs, and webhook secrets are not documented here. Retrieve them from the platform secrets store or the Stripe dashboard under authorised credentials only. Do not commit these values to source control.

Auth System

Leader Auth & Subscription Tiers

JWT HS256 HTTP-only SameSite=strict cookies. Leader auth gate requires status = 'approved'. Admin auth uses a separate credential store — not the users table. Client-side auth context in src/portal/auth/.

Guestguest

Free

  • Public profile view
  • Browse executive directory
  • Submit application
Associatetier1

AUD $149/mo

  • Social listening
  • Smart Inbox
  • Executive Profile Hub
  • Inbound Matching
Protier2

AUD $349/mo

  • All Tier 1 features
  • AI Content Co-Pilot
  • Social Proof Builder
  • Content Scheduler
  • Playbook Library
Elitetier3

AUD $699/mo

  • All Tier 2 features
  • Taackk Amplify
  • Engagement Configurator
  • Pricing Calculator
  • Contracting & Escrow

Key Auth Files

src/portal/auth/types.ts

LeaderUser, SubscriptionTier, PermissionFlags interfaces — 12-feature permission matrix across 4 tiers

src/portal/auth/context.tsx

LeaderAuthProvider — React context wrapping the entire app via RootLayout

src/portal/auth/hooks.ts

useLeaderPermissions() — resolves feature flags from current tier

src/components/TierGate.tsx

Subscription-tier gating component with blurred locked previews and upgrade modal

Test Credentials

Test account credentials are not documented on this page. Retrieve them from the internal secrets store or request access through the IAM portal. Do not share credentials in documentation, chat, or version control.

Admin Portal

Admin Routes & RBAC

14 admin routes with role-based access control. All routes require requireAdminAuth middleware. Minimum role is noted per route.

/admin
Dashboardviewer

Overview KPIs, recent activity, system health.

/admin/features
Feature Flagsoperator

Toggle platform features per scope. All changes written to feature_flag_audit_log.

/admin/customers
Customersoperator

Leader and business account management, status changes, tier overrides.

/admin/audit
Audit Logoperator

Paginated compliance log viewer with filters for actor, table, action, and date range.

/admin/iam
IAMsuper_admin

Employee management, team assignments, policy configuration, effective permissions.

/admin/impersonation
Impersonationsuper_admin

Customer impersonation tickets with step-up MFA and dual-control approval workflow.

/admin/applications
Applicationsoperator

Leader application review queue with asset review and status management.

/admin/customer-lifecycle
Customer Lifecycleoperator

Onboarding funnel, churn risk, and lifecycle stage management.

/admin/templates
Email Templatesoperator

Edit transactional email subject and HTML body. Changes persist to DB.

/admin/email-validation
Email Validationoperator

Duplicate detection, cluster merge/split, and application flag management.

/admin/algorithm-library
Algorithm Libraryadmin

Matching algorithm versioning, promotion, and A/B test configuration.

/admin/pricing
Pricingadmin

Subscription plan management, archiving, and pricing overrides.

/admin/security-scan
Security Scansuper_admin

Trigger and review security scans. Results persisted to security_scan_reports.

/admin/incidents
Incidentssuper_admin

Data breach incident response. GDPR 72-hour DPA countdown, DPA notification modal.

Routing

Pages & Routes

All routes registered in src/routes.tsx. RootLayout (header + footer) wraps every public page. SSR via React Router v8 data router.

/
HomepageMarketing landing page with hero, value props, pricing grids, and leader spotlights.
/pricing
PricingTab-toggled pricing for businesses and leaders, comparison table, FAQ.
/about
AboutFounding story, trust and security (SOC 2, AES-256, GDPR/CCPA), partner badges.
/onboarding
Business Onboarding4-step wizard: company info → leader needs → plan selection → contact details.
/apply
Leader Application4-step wizard: profile → track record → availability → tier selection → Stripe Checkout.
/login
LoginSplit-panel auth page. Email/password with lockout protection. Demo shortcuts available in non-production environments only.
/profiles
Executive ProfilesSearchable leader directory.
/portal/*
Business Portal13 authenticated pages: Build a Brief wizard, analytics suite, org-chart, marketplace, subscription management.
/leader-portal/*
Leader PortalDashboard, profile builder (8-section, AI generation, LinkedIn import), content library, subscription tier manager, analytics suite.
/admin/*
Admin Portal14 admin routes with RBAC. See Admin Routes section for full listing.
/developers
DevelopersThis page. Internal only — noindex, nofollow.
Stack

Technology Stack

Key dependencies and architectural decisions.

Frontend

  • React 19 + TypeScript
  • Vite (SSR via React Router v8)
  • Tailwind CSS + shadcn/ui
  • Motion (animations)
  • @dr.pogodin/react-helmet (SSR head)

Backend

  • Express.js (API routes)
  • MySQL + Drizzle ORM
  • Custom TypeScript migrations (scripts/migrations/)
  • Stripe (AU, AUD, platform-managed)
  • WebSocket server (real-time messaging)

Security

  • JWT HS256 HTTP-only SameSite=strict cookies
  • AES-256-GCM field-level encryption at rest
  • NDJSON logger with PII redaction
  • Rate limiting + brute-force defence
  • security.txt at /.well-known/security.txt

Compliance

  • SOC 2 Type II architecture
  • GDPR Art. 17 anonymization + Art. 33 incident response
  • ISO 27001 A.9.4 / A.10.1 / A.12.4 / A.16.1
  • Immutable append-only audit log
  • Data retention scheduler
  • GDPR data export endpoint

Content Layer

  • src/content/ — all user-visible copy
  • virtual:content imports only
  • No content prop-drilling into sub-components
  • Inline .map() bodies for editable lists

Key Rules

  • No hardcoded hex colors in components
  • No VITE_ prefix on secrets
  • Secrets via getSecret() from #airo/secrets
  • .js extensions required in API route imports
  • No .returning() in MySQL (use insertId pattern)
  • db.execute<T>() returns [T[], FieldPacket[]] tuple