# Business Requirements Document
# Navagoo Social Media Management Integration with Upload-Post
**Final Consolidated Requirements**

> **Source of truth for the Manage Social Media feature.** Any change to behaviour
> or scope must update this document first. The implementation lives in:
> - `common/components/UploadPostClient.php` · `SocialMediaService.php`
> - `common/models/{ShopSocialSettings,UploadPostProfile,SocialAccount,SocialPostingLimit,SocialPost,SocialAuditLog}.php`
> - `backend/controllers/ShopSocialController.php` · `backend/views/shop-social/`
> - `frontend/controllers/SocialMediaController.php` · `frontend/views/social-media/`
> - `api/controllers/SocialController.php`
> - `console/controllers/SocialPostStatusController.php` (status poller; Upload-Post has no webhooks)

| Document Item | Details |
|---|---|
| Product / Platform | Navagoo |
| Feature | Social Media Management Integration |
| Integration Partner | Upload-Post |
| Primary Users | Navagoo Admin, Authorized Navagoo User, Salon Owner |
| Document Purpose | Define business and functional requirements for implementation by the development team |

---

## 1. Objective

Navagoo needs to provide a Social Media Management feature for selected salons. The feature will allow Navagoo Admin to enable social media management for a salon, after which the system will automatically create or validate the salon Upload-Post user profile, generate the social account connection link, and send the link to the salon owner by email only.

After the salon owner connects their social media accounts through Upload-Post, Navagoo will automatically synchronize the connected accounts and allow publishing or scheduling posts based on the salon active package and configured posting limits.

---

## 2. Business Scope

### 2.1 In Scope

| Area | Requirement |
|---|---|
| Feature enablement | Admin enables Social Media Management privilege per salon. |
| Upload-Post profile management | System creates or validates the salon Upload-Post profile automatically. |
| Connection link generation | System automatically generates the Upload-Post social account connection link. |
| Email delivery | System sends the connection link to the salon owner by email only. |
| Social account connection | Salon owner connects social media accounts through Upload-Post. |
| Account synchronization | System automatically synchronizes connected accounts/pages from Upload-Post. |
| Posting limits | Admin defines post limits per salon and per platform/page. |
| Publishing | Authorized users can publish posts to selected connected social accounts. |
| Scheduling | Authorized users can schedule posts for future publishing. |
| Usage tracking | System tracks used and remaining post balance. |
| Audit and monitoring | System logs setup, email, connection, posting, scheduling, usage, and errors. |

### 2.2 Out of Scope

| Area | Exclusion |
|---|---|
| Automatic setup for all salons | Upload-Post profile should not be created when a salon is created. |
| Manual profile creation by Admin | Admin should not manually create Upload-Post profiles. |
| Manual connection link generation by Admin | Admin should not manually generate the social connection link. |
| Manual approval of connected accounts | Admin should not manually approve or enable connected accounts/pages. |
| SMS / WhatsApp / portal notification | Connection link should be sent by email only in this phase. |
| Social media password storage | Navagoo must not store social media passwords. |
| Internal OAuth development | Social media OAuth connection is handled by Upload-Post. |

---

## 3. Final Business Flow

| Step | Actor | Action |
|---|---|---|
| 1 | Admin | Opens the salon profile in Navagoo. |
| 2 | Admin | Enables Social Media Management privilege for the salon. |
| 3 | System | Creates or validates the salon Upload-Post user profile. |
| 4 | System | Automatically generates the Upload-Post social account connection link. |
| 5 | System | Saves the Upload-Post profile reference and connection link in Navagoo. |
| 6 | System | Sends the social account connection link to the salon owner by email only. |
| 7 | Salon Owner | Opens the link from the email and connects social media accounts through Upload-Post. |
| 8 | System | Receives or validates the connection status from Upload-Post. |
| 9 | System | Automatically synchronizes connected social accounts/pages and makes eligible accounts available for posting based on the salon active package and posting limits. |
| 10 | Admin | Defines or updates the posting limit/package per salon and social page/platform. |
| 11 | Authorized User | Creates or schedules posts for the salon. |
| 12 | System | Validates feature privilege, account status, package eligibility, and remaining post limit. |
| 13 | System | Sends publish/schedule request to Upload-Post. |
| 14 | System | Saves post result, updates usage, and logs activity. |

---

## 4. Functional Business Requirements

### BR-01: Enable Social Media Management Privilege per Salon
**Requirement:** Admin must be able to manually enable or disable the Social Media Management privilege for selected salons only.

| ID | Requirement |
|---|---|
| BR-01.1 | Social Media Management privilege must be disabled by default for all salons. |
| BR-01.2 | Admin can enable the privilege from the salon profile or package/subscription screen. |
| BR-01.3 | Enabling the privilege should trigger Upload-Post profile management integration automatically. |
| BR-01.4 | Upload-Post profile should not be created when a salon is created. |
| BR-01.5 | If the privilege is disabled, the salon cannot connect accounts, publish posts, or schedule posts. |
| BR-01.6 | Enabling or disabling the privilege must be recorded in the audit log. |
| BR-01.7 | If the salon subscription/package is inactive, the system should prevent posting even if the profile exists. |

### BR-02: Automatic Upload-Post Profile Creation and Validation
**Requirement:** Once Admin enables the Social Media Management privilege, Navagoo should automatically create or validate a dedicated Upload-Post user profile for the salon.

| ID | Requirement |
|---|---|
| BR-02.1 | System should check whether the salon already has an Upload-Post user profile. |
| BR-02.2 | If no profile exists, system should create a new Upload-Post profile. |
| BR-02.3 | The Upload-Post username should use a stable Navagoo identifier, such as `navagoo_salon_{salonId}`. |
| BR-02.4 | If the profile already exists, system should reuse the existing profile and avoid duplicate creation. |
| BR-02.5 | System should save the Upload-Post username/profile reference against the salon record. |
| BR-02.6 | System should store profile status: Not Created, Setup In Progress, Created, Active, Failed, or Disabled. |
| BR-02.7 | If profile creation fails, system should log the error and mark setup status as Failed. |
| BR-02.8 | System should allow retrying profile setup through a backend retry job or controlled admin action. |
| BR-02.9 | Upload-Post API key must be stored securely in backend configuration or secret manager. |

### BR-03: Automatic Social Account Connection Link Generation
**Requirement:** After the Upload-Post profile is created or validated, Navagoo should automatically generate the social account connection link through Upload-Post user profile management integration.

| ID | Requirement |
|---|---|
| BR-03.1 | System should automatically generate the social account connection link after successful profile creation or validation. |
| BR-03.2 | Admin should not manually generate the connection link. |
| BR-03.3 | System should call the Upload-Post connection/JWT URL generation API using the salon Upload-Post username/profile reference. |
| BR-03.4 | System should save the generated connection link in Navagoo. |
| BR-03.5 | System should store link creation date, expiry date if available, and link status. |
| BR-03.6 | System should regenerate a new connection link if the previous link expires and the salon owner has not completed connection. |
| BR-03.7 | The connection link should redirect the salon owner back to Navagoo after account connection, where supported. |
| BR-03.8 | The connection page should use Navagoo branding where supported, such as logo, title, description, and allowed platforms. |

### BR-04: Send Social Account Connection Link by Email Only
**Requirement:** After the Upload-Post profile is created/validated and the connection link is generated, Navagoo should automatically send the link to the salon owner by email only.

| ID | Requirement |
|---|---|
| BR-04.1 | System should send the social account connection link to the salon owner registered email address. |
| BR-04.2 | The connection link should not be sent through SMS, WhatsApp, or portal notification in this phase. |
| BR-04.3 | Email should be sent automatically after successful profile creation and connection link generation. |
| BR-04.4 | Email should include clear instructions for connecting social media accounts. |
| BR-04.5 | Email should include link expiry information if available. |
| BR-04.6 | System should log email delivery status: Pending, Sent, Failed, or Retried. |
| BR-04.7 | If email sending fails, system should retry based on configured retry policy. |
| BR-04.8 | Admin can view email sending status for the salon. |
| BR-04.9 | Admin should not manually generate or modify the technical connection link. |

#### Suggested Email Template

> **Subject:** Connect Your Salon Social Media Accounts
>
> Dear [Salon Owner Name],
>
> Your salon has been enabled for Navagoo Social Media Management.
>
> Please use the link below to connect your salon social media accounts:
>
> [Connection Link]
>
> Through this link, you can connect your supported social media accounts so Navagoo can publish or schedule posts according to your active package.
>
> Please complete the connection before the link expires.
>
> Best regards,
> Navagoo Team

### BR-05: Salon Owner Connects Social Media Accounts
**Requirement:** Salon owner should open the email link and connect their social media accounts through Upload-Post.

| ID | Requirement |
|---|---|
| BR-05.1 | Salon owner opens the connection link from the email. |
| BR-05.2 | Salon owner can connect one or more supported social media accounts. |
| BR-05.3 | Social media authentication must be handled by Upload-Post. |
| BR-05.4 | Navagoo must not store social media passwords. |
| BR-05.5 | After connection, salon owner should be redirected to Navagoo confirmation page if supported. |
| BR-05.6 | If the connection fails, the system should show a clear error or provide the latest valid connection link by email resend flow. |

### BR-06: Automatic Synchronization of Connected Social Accounts
**Requirement:** After the salon owner connects social media accounts through Upload-Post, Navagoo should automatically retrieve, synchronize, and validate the connected accounts/pages. Admin should not manually approve or enable each connected social account/page.

| ID | Requirement |
|---|---|
| BR-06.1 | System should automatically retrieve connected social accounts/pages from Upload-Post. |
| BR-06.2 | System should update account status in Navagoo without requiring Admin approval. |
| BR-06.3 | Connected accounts/pages should become available for posting if the salon has active Social Media Management privilege and valid posting limits. |
| BR-06.4 | System should prevent posting to disconnected, expired, invalid, or unsupported accounts. |
| BR-06.5 | System should display connected accounts/pages to Admin for visibility only. |
| BR-06.6 | Admin should not be required to manually enable each connected social account/page. |
| BR-06.7 | System should log all account synchronization and status updates. |

### BR-07: Configure Posting Limits per Salon and Platform/Page
**Requirement:** Admin must be able to define posting limits for each salon based on the salon package/subscription.

| ID | Requirement |
|---|---|
| BR-07.1 | Admin can define monthly post limit per salon. |
| BR-07.2 | Admin can define limits per platform/page, for example Instagram = 20 posts/month and TikTok = 10 posts/month. |
| BR-07.3 | Admin can define whether scheduled posts are counted when scheduled or only when published. |
| BR-07.4 | System should calculate used posts and remaining posts per salon/platform/page. |
| BR-07.5 | System should prevent publishing or scheduling if the salon exceeds the allowed limit. |
| BR-07.6 | Admin can increase, decrease, pause, or reset the posting limit. |
| BR-07.7 | All posting limit changes must be recorded in the audit log. |
| BR-07.8 | Posting limits should reset according to the salon package billing cycle or configured monthly reset date. |

### BR-08: Publish Posts to Selected Social Media Accounts
**Requirement:** Authorized Navagoo users should be able to publish posts to selected connected social media accounts for a salon.

| ID | Requirement |
|---|---|
| BR-08.1 | User can select a salon. |
| BR-08.2 | System should show only connected, valid, and eligible social accounts/pages for that salon. |
| BR-08.3 | User can create post content, including text/caption and supported media attachments. |
| BR-08.4 | User can select one or more social platforms/pages. |
| BR-08.5 | Before publishing, system must validate Social Media Management privilege, package status, account status, and remaining post limit. |
| BR-08.6 | If validation passes, system sends publish request to Upload-Post. |
| BR-08.7 | System saves Upload-Post response, post ID/reference, selected platforms, status, and timestamp. |
| BR-08.8 | If posting succeeds on one platform and fails on another, system should store platform-level results. |
| BR-08.9 | Used post count should be updated based on the agreed business rule: successful posts only, unless otherwise configured. |

### BR-09: Schedule Posts
**Requirement:** Authorized Navagoo users should be able to schedule posts for future publishing.

| ID | Requirement |
|---|---|
| BR-09.1 | User can choose between Publish Now and Schedule. |
| BR-09.2 | If Schedule is selected, user must enter future date and time. |
| BR-09.3 | System should validate that selected date/time is in the future. |
| BR-09.4 | System must validate Social Media Management privilege, package status, account status, and remaining post limit before scheduling. |
| BR-09.5 | Scheduled posts should be saved in Navagoo with Scheduled status. |
| BR-09.6 | System should send scheduling request to Upload-Post if supported by the selected endpoint. |
| BR-09.7 | Admin or authorized user can view scheduled posts per salon. |
| BR-09.8 | Admin or authorized user can cancel or edit scheduled posts if supported by Upload-Post and Navagoo business rules. |
| BR-09.9 | Scheduled posts should count against the post limit based on the configured business rule. |

### BR-10: Posting History and Status Tracking
**Requirement:** Navagoo should maintain posting history for each salon.

| ID | Requirement |
|---|---|
| BR-10.1 | Admin can view social post history from the salon profile. |
| BR-10.2 | History should show post caption, media, platforms, status, created by, created date, and scheduled date if applicable. |
| BR-10.3 | Each platform should have its own posting status. |
| BR-10.4 | Supported statuses should include Draft, Scheduled, Published, Failed, Cancelled, and Retry Pending. |
| BR-10.5 | Failed posts should show error reason returned by Upload-Post. |
| BR-10.6 | Admin can filter history by salon, platform, status, and date range. |
| BR-10.7 | Retry should be available only when account status and post limits are valid. |

### BR-11: Admin Dashboard and Usage Monitoring
**Requirement:** Admin should have visibility into social media management usage and integration health.

| KPI / Metric | Description |
|---|---|
| Enabled salons | Number of salons with Social Media Management privilege enabled. |
| Setup failed salons | Salons where Upload-Post setup failed. |
| Waiting for connection | Salons where email link was sent but accounts are not connected yet. |
| Connected salons | Salons with one or more connected social accounts. |
| Connected accounts by platform | Count of connected accounts by platform. |
| Published posts this month | Number of published posts in current period. |
| Scheduled posts | Number of future scheduled posts. |
| Failed posts | Number of failed posts by platform/error. |
| Limit exceeded salons | Salons that reached package limit. |
| Remaining post balance | Remaining posts by salon/platform/page. |
| Email delivery failures | Failed connection-link emails. |

### BR-12: Security, Audit, and Permissions
**Requirement:** All social media integration actions must be secure and auditable.

| ID | Requirement |
|---|---|
| BR-12.1 | Upload-Post API key must be stored securely and never exposed to frontend. |
| BR-12.2 | Only authorized Navagoo users can enable or disable Social Media Management privilege. |
| BR-12.3 | Only authorized users can publish or schedule posts. |
| BR-12.4 | Only authorized Admins can configure posting limits. |
| BR-12.5 | System must log feature enablement, profile creation, link generation, email sending, account synchronization, publishing, scheduling, cancellation, retry, and limit changes. |
| BR-12.6 | Audit log should include actor, action, timestamp, salon ID, old value, new value, and result. |
| BR-12.7 | Navagoo must not store social media passwords. |
| BR-12.8 | Connection links should be treated as sensitive and should not be exposed publicly. |
| BR-12.9 | System should support deactivating posting for a salon if subscription is inactive, package expired, or account status is invalid. |

---

## 5. Suggested Data Model

### 5.1 Salon Social Management Configuration

| Field | Description |
|---|---|
| `salon_id` | Navagoo salon ID |
| `social_management_enabled` | Yes/No |
| `social_management_status` | Disabled / Setup In Progress / Active / Failed |
| `upload_post_username` | Upload-Post profile username |
| `upload_post_profile_status` | Not Created / Created / Failed / Disabled |
| `connection_link` | Latest generated connection link |
| `connection_link_status` | Active / Expired / Used / Failed |
| `connection_link_created_on` | Link creation date |
| `connection_link_expiry_on` | Link expiry date, if available |
| `connection_email_status` | Pending / Sent / Failed / Retried |
| `last_sync_on` | Last account sync date |
| `last_error` | Last integration error |

### 5.2 Connected Social Account

| Field | Description |
|---|---|
| `salon_id` | Related salon |
| `platform` | Instagram / TikTok / Facebook / YouTube / etc. |
| `account_id` | External account/page ID |
| `account_name` | Account/page display name |
| `account_status` | Connected / Invalid / Expired / Disconnected |
| `eligible_for_posting` | Yes/No |
| `last_validated_on` | Last validation date |
| `last_error` | Last account-related error |

### 5.3 Posting Limit

| Field | Description |
|---|---|
| `salon_id` | Related salon |
| `platform` | Social media platform |
| `account_id` | Optional account/page |
| `monthly_post_limit` | Allowed monthly posts |
| `used_post_count` | Used posts in current cycle |
| `remaining_post_count` | Remaining posts |
| `reset_date` | Next reset date |
| `include_scheduled_posts` | Yes/No |
| `status` | Active / Paused / Expired |

### 5.4 Social Post

| Field | Description |
|---|---|
| `post_id` | Navagoo post ID |
| `salon_id` | Related salon |
| `content` | Caption/text |
| `media_url` | Image/video URL |
| `platforms` | Selected platforms |
| `post_type` | Publish Now / Scheduled |
| `scheduled_on` | Scheduled date/time |
| `status` | Draft / Scheduled / Published / Failed / Cancelled |
| `upload_post_reference` | External reference from Upload-Post |
| `created_by` | User who created post |
| `created_on` | Creation timestamp |

---

## 6. System Statuses

| Status | Meaning |
|---|---|
| Social Feature Disabled | Salon does not have Social Media Management privilege. |
| Setup In Progress | Feature enabled and system is creating/validating Upload-Post profile. |
| Profile Created | Upload-Post profile exists. |
| Link Generated | Connection link generated by system. |
| Email Sent | Connection link email sent to salon owner. |
| Waiting for Salon Connection | Salon owner has not connected social accounts yet. |
| Connected | One or more social accounts are connected. |
| Ready for Posting | Connected account exists and valid posting limit is configured. |
| Setup Failed | Profile, link generation, or email sending failed. |
| Reconnection Required | Social account token/permission expired. |
| Disabled | Admin disabled the feature. |

---

## 7. Acceptance Criteria Summary

| ID | Acceptance Criteria |
|---|---|
| AC1 | Social Media Management is disabled by default for all salons. |
| AC2 | Admin can enable the feature for selected salons only. |
| AC3 | Upload-Post profile is created only after Admin enables the feature. |
| AC4 | System automatically creates or validates the Upload-Post profile. |
| AC5 | System automatically generates the social account connection link. |
| AC6 | Admin does not manually generate the connection link. |
| AC7 | System sends the connection link to salon owner by email only. |
| AC8 | Salon owner connects social accounts through Upload-Post. |
| AC9 | System automatically synchronizes connected accounts/pages. |
| AC10 | Admin does not manually approve or enable connected social accounts/pages. |
| AC11 | Connected accounts become available for posting based on active privilege, package, and posting limits. |
| AC12 | Admin can configure monthly posting limits per salon/platform/page. |
| AC13 | System prevents publishing/scheduling if the feature is disabled, account is invalid, package is inactive, or limit is exceeded. |
| AC14 | Authorized users can publish posts to selected eligible social accounts. |
| AC15 | Authorized users can schedule posts for future publishing. |
| AC16 | System tracks posting usage and remaining limits. |
| AC17 | Admin can view posting history, failed posts, scheduled posts, and usage dashboard. |
| AC18 | All actions are captured in audit logs. |
| AC19 | API keys and social credentials are secured; Navagoo must not store social media passwords. |

---

## 8. Developer API Assumptions

| Function | Expected Integration |
|---|---|
| Create user profile | Upload-Post user profile API |
| Validate existing profile | Upload-Post user profile management/list API |
| Generate connection link | Upload-Post JWT/connection URL generation API |
| Connect social accounts | Upload-Post OAuth connection page |
| Retrieve connected accounts | Upload-Post user/profile account APIs |
| Publish content | Upload-Post upload/publish API |
| Schedule content | Upload-Post schedule/upload management APIs |
| Retrieve post history | Upload-Post upload/history APIs |
| Authentication | API key stored securely in backend |

> Developers should verify exact request and response payloads in the latest Upload-Post API reference before implementation.

---

## 9. References

- Upload-Post User Profile Integration Guide: <https://docs.upload-post.com/guides/user-profile-integration/>
- Upload-Post API Reference: <https://docs.upload-post.com/api/reference/>
- Upload-Post Product Site: <https://www.upload-post.com/>

---

*Navagoo — Social Media Management Integration Requirements*