Barkly Community Market

Functional Requirements Document (FRD)

Project: Barkly Community Market Organization: Barkly Labs Document version: 1.0 Status: Draft — proposed requirements Priority: MVP-first Migration approach: Extend the existing Barkly Labs avatar-store web application.

1. Purpose

Barkly Community Market is a community-oriented marketplace that enables independent creators, artists, makers, and developers to showcase and sell digital and physical products.

The marketplace will evolve from the existing Barkly Labs avatar store. The implementation must preserve reusable code, existing assets, working features, and compatible product data wherever practical.

The marketplace will support:

Digital products, including avatars, emotes, icons, profile pictures, and downloadable creative assets.

Physical products, including stickers, prints, handmade goods, maker projects, and small hardware products.

Custom commissions and creator services.

Individual seller profiles and product listings.

Product discovery, purchasing, and order fulfillment.

Administrative review, moderation, and marketplace management.

The marketplace is intended to support Barkly Labs' wider mission of making technology and creative opportunities more accessible to people.

2. Goals

Convert the existing avatar store into a general-purpose community marketplace.

Reuse the existing application architecture and assets rather than unnecessarily rebuilding them.

Enable approved community members to submit products for sale.

Provide a consistent shopping experience for digital and physical goods.

Establish a manageable administrative workflow for sellers, listings, and orders.

Support a small pilot before opening the marketplace to the wider community.

Maintain accessibility, privacy, security, and transparent marketplace policies.

3. Scope

3.1 MVP scope

The initial release must include:

Public marketplace storefront.

Product browsing, search, and category filtering.

Product detail pages.

Seller profiles.

Digital, physical, and commission product types.

Seller applications or administrator-created seller accounts.

Product submission and approval workflows.

Shopping cart and checkout, subject to payment-provider integration.

Order records and status tracking.

Digital delivery or fulfillment instructions.

Physical inventory and shipping-status tracking.

Administrator dashboard and moderation controls.

Preservation or migration of existing avatar products and assets.

Responsive layouts and basic accessibility support.

3.2 Future scope

The following features may be introduced after the MVP:

Automated seller payouts and configurable marketplace commissions.

Multi-seller carts and split payments.

Reviews and ratings.

Seller subscriptions.

Advanced analytics and recommendations.

Shipping-label integrations.

Promotional campaigns, coupons, and loyalty systems.

Advanced dispute management.

These features must not be assumed to exist in the MVP unless the existing application already provides them and they pass testing.

4. User roles

FR-ROLE-001: Visitor

A visitor must be able to browse published products, search the marketplace, view seller profiles, and read marketplace policies without creating an account.

FR-ROLE-002: Customer

An authenticated customer must be able to manage their shopping activity, view their orders, and access products they have purchased according to the applicable delivery rules.

FR-ROLE-003: Seller

An approved seller must be able to manage their seller profile, create and edit product listings, submit listings for review, and fulfill orders assigned to them.

FR-ROLE-004: Administrator

An administrator must be able to manage users, approve sellers, moderate listings, review orders, and manage marketplace configuration.

FR-ROLE-005: Moderator

If a separate moderator role is implemented, moderators must be able to review reported content and take explicitly authorized moderation actions without automatically receiving payment or financial administration permissions.

FR-ROLE-006: Role-based permissions

The application must enforce permissions on the server, not only by hiding interface elements. Users must not be able to access another seller's private listings, orders, customer information, or administrative functions by modifying a URL or request.

5. Functional requirements

5.1 Storefront and navigation

FR-STORE-001 — Marketplace homepage

The system shall display a marketplace homepage containing marketplace branding, product categories, featured products, and links to seller shops.

FR-STORE-002 — Product catalog

The system shall display published products in a browsable catalog.

Each product card shall display, where applicable:

Product image.

Product title.

Price and currency.

Product type.

Seller or shop name.

Availability status.

FR-STORE-003 — Search

Visitors and customers shall be able to search published products by relevant text fields, including product title and description.

FR-STORE-004 — Category filtering

Users shall be able to filter products by category and product type.

FR-STORE-005 — Sorting

The catalog shall support basic sorting, such as newest products first and price ascending or descending.

FR-STORE-006 — Empty and error states

The interface shall display understandable messages when no products match a search, a category contains no products, or a request fails.

FR-STORE-007 — Responsive presentation

The storefront shall remain usable on desktop, tablet, and mobile screen sizes.

5.2 Product management

FR-PROD-001 — General product model

The system shall support a common product model that can represent digital products, physical products, and commissions without requiring separate storefront applications.

FR-PROD-002 — Required listing fields

Each product listing shall contain:

Unique product identifier.

Seller identifier.

Product title.

Description.

Price.

Currency.

Product type.

Category.

At least one product image or an approved visual placeholder.

Listing status.

Creation and modification timestamps.

FR-PROD-003 — Product types

The system shall support the following product types:

Digital product.

Physical product.

Commission or custom service.

FR-PROD-004 — Digital product details

Digital listings shall support a digital delivery method and, where applicable, a downloadable asset reference.

Paid downloadable files shall not be exposed through unrestricted public file URLs.

FR-PROD-005 — Physical product details

Physical listings shall support inventory quantity, availability, and applicable shipping information.

FR-PROD-006 — Commission details

Commission listings shall support information such as service description, expected deliverables, estimated turnaround, and instructions for requesting custom work.

FR-PROD-007 — Listing validation

The system shall reject or flag listings that lack required fields, have invalid prices, or contain unsupported product types.

FR-PROD-008 — Listing ownership

Sellers shall be able to create and edit their own listings but shall not be able to modify listings owned by other sellers.

FR-PROD-009 — Listing states

Listings shall support the following states:

Draft.

Pending review.

Published.

Rejected.

Archived.

Only published listings shall appear in the public catalog.

FR-PROD-010 — Listing preservation

Existing avatar products shall remain available for migration. The migration must preserve compatible product identifiers, titles, descriptions, images, prices, and other useful metadata.

5.3 Seller accounts and profiles

FR-SELL-001 — Seller application

The system shall allow eligible users to request seller access, unless an administrator creates their seller account directly.

FR-SELL-002 — Seller approval

An administrator shall be able to approve or reject a seller application.

FR-SELL-003 — Seller profile

Each approved seller shall have a public profile containing a shop name, description, profile image or avatar, and published products.

FR-SELL-004 — Seller editing

Sellers shall be able to update their permitted profile fields.

FR-SELL-005 — Seller status

Administrators shall be able to suspend or deactivate seller access. Suspension shall prevent new listings and other seller actions according to the configured permissions.

FR-SELL-006 — Seller attribution

Each published product shall identify its seller.

FR-SELL-007 — Seller privacy

The public profile shall not expose private account details, payment credentials, private contact information, or customer order information.

5.4 Shopping cart and checkout

FR-CART-001 — Add to cart

Customers shall be able to add eligible products to a shopping cart.

FR-CART-002 — Cart management

Customers shall be able to view cart contents, change permitted quantities, and remove items.

FR-CART-003 — Availability validation

Before accepting an order, the system shall validate that each item is still published and available and that sufficient physical inventory exists.

FR-CART-004 — Price validation

The server shall calculate the authoritative product subtotal and any applicable shipping, tax, fees, and discounts. The client shall not be trusted to supply the final order amount.

FR-CART-005 — Checkout

The system shall provide a checkout process through a supported payment provider or an explicitly configured alternative purchasing workflow.

FR-CART-006 — Payment confirmation

The system shall mark an order as paid only after receiving and validating a trusted payment confirmation. Duplicate payment notifications shall not create duplicate orders or fulfillment actions.

FR-CART-007 — Payment failure

If payment fails or is canceled, the system shall not treat the order as paid or release paid digital downloads.

FR-CART-008 — Clear pricing

Customers shall see the applicable total and any known additional charges before confirming the purchase.

FR-CART-009 — Mixed-seller orders

The initial implementation may restrict a cart to one seller if that substantially simplifies payment and fulfillment. If so, the restriction must be communicated before checkout.

FR-CART-010 — Payment-provider configuration

Payment processing shall use a supported provider and secure configuration. The application shall not store raw payment-card details.

5.5 Orders and fulfillment

FR-ORDER-001 — Order creation

The system shall create a persistent order record associated with the customer and the purchased products.

FR-ORDER-002 — Order line items

Each order shall preserve the product title, quantity, unit price, seller, and relevant fulfillment information as recorded at purchase time.

FR-ORDER-003 — Order status

Orders shall support distinguishable payment and fulfillment states, such as:

Awaiting payment.

Paid.

Processing.

Fulfilled.

Completed.

Canceled.

Refunded.

The implementation may use separate payment and fulfillment status fields to avoid conflicting states.

FR-ORDER-004 — Customer order history

Customers shall be able to view their own orders and relevant status information.

FR-ORDER-005 — Seller order access

Sellers shall be able to view only the order information necessary to fulfill their own sales.

FR-ORDER-006 — Digital fulfillment

After confirmed payment, the system shall make eligible digital products available to the purchasing customer or provide the configured delivery instructions.

FR-ORDER-007 — Download authorization

Digital download access shall be restricted to eligible purchasers and authorized administrators. Access shall be revocable where technically supported.

FR-ORDER-008 — Physical fulfillment

Sellers shall be able to mark physical orders as processing and shipped, and provide tracking information when available.

FR-ORDER-009 — Inventory

The system shall update physical inventory when an order is confirmed according to the chosen reservation policy. It shall prevent inventory from becoming negative.

FR-ORDER-010 — Notifications

The system shall provide appropriate order confirmations and status notifications through the available notification mechanism.

FR-ORDER-011 — Refunds and cancellations

The system shall record authorized refunds and cancellations and reflect them in the order history. Refund processing must be consistent with the payment provider and marketplace policy.

5.6 Marketplace administration and moderation

FR-ADMIN-001 — Administrative dashboard

Administrators shall have access to a protected dashboard for managing sellers, listings, and orders.

FR-ADMIN-002 — Listing review

Administrators shall be able to review pending listings and publish or reject them.

FR-ADMIN-003 — Rejection reasons

Administrators shall be able to record a reason for rejecting a listing and make that reason available to the seller.

FR-ADMIN-004 — Content reporting

Users shall have a way to report a product or seller for review.

FR-ADMIN-005 — Listing removal

Authorized administrators shall be able to unpublish or archive listings that violate marketplace policy.

FR-ADMIN-006 — Seller management

Administrators shall be able to review seller applications, approve or reject applicants, and suspend seller access when necessary.

FR-ADMIN-007 — Order oversight

Administrators shall be able to inspect order status and investigate fulfillment problems within their authorized access.

FR-ADMIN-008 — Audit records

The system shall record important administrative actions, including listing approvals, seller suspensions, and order-status overrides.

FR-ADMIN-009 — Permission enforcement

Administrative operations shall require explicit server-side authorization.

5.7 Migration from the avatar store

FR-MIG-001 — Existing application audit

Before implementation, the development process shall identify the existing framework, routes, components, data models, database, authentication, storage, payment integration, and tests.

FR-MIG-002 — Reuse assessment

Existing code shall be classified as reusable, reusable with modification, replaceable, or obsolete. Working components shall not be replaced without a documented reason.

FR-MIG-003 — Asset preservation

Existing logos, icons, avatar artwork, product images, fonts, styles, and other relevant assets shall be preserved where licensing and technical compatibility permit.

FR-MIG-004 — Data migration

Existing avatar products shall be migrated or mapped into the generalized product model.

FR-MIG-005 — Migration safety

The migration shall be repeatable or safely recoverable. It shall not silently duplicate products or discard existing data.

FR-MIG-006 — Compatibility

Existing account functionality and useful URLs shall be preserved where practical. Any changed routes shall have appropriate redirects when supported by the application.

FR-MIG-007 — Rollback

The team shall retain a backup and a documented method to restore the previous application if the migration fails.

FR-MIG-008 — Regression testing

Existing storefront functionality shall be tested after migration, including product display, navigation, and any retained cart or account functionality.

5.8 Marketplace policies and seller transparency

FR-POLICY-001 — Marketplace rules

The marketplace shall publish rules for prohibited products, intellectual property, harassment, fraud, and seller conduct.

FR-POLICY-002 — Seller terms

Sellers shall be shown the applicable seller terms before being approved or before publishing their first listing.

FR-POLICY-003 — Product rights

Sellers shall confirm that they have the rights necessary to sell the content they submit.

FR-POLICY-004 — Digital licensing

Digital listings shall describe the applicable usage license or terms, such as personal use or commercial use, where relevant.

FR-POLICY-005 — Returns and refunds

The marketplace shall explain applicable cancellation, refund, and return policies before purchase.

FR-POLICY-006 — Physical shipping

Physical listings shall communicate shipping arrangements, relevant delivery restrictions, and any known shipping charges.

FR-POLICY-007 — Fees and payouts

Any marketplace fees, seller charges, payout arrangements, and payout timing shall be clearly disclosed before a seller agrees to participate.

FR-POLICY-008 — Privacy

The marketplace shall publish a privacy notice describing the collection and use of account, order, and seller information.

6. Core data entities

The implementation shall provide equivalent data structures using the project's existing database conventions.

The project may use existing entities where suitable. The table is a logical model, not a requirement to create exactly one database table per entity.

7. Non-functional requirements

Although this document focuses on functionality, the MVP shall also satisfy these baseline requirements:

NFR-001 — Security: Authentication, authorization, input validation, file handling, and payment confirmation must be implemented securely.

NFR-002 — Accessibility: Core shopping and seller workflows must be usable with keyboard navigation, clear focus indicators, labels, readable contrast, and appropriate alternative text.

NFR-003 — Privacy: Users must not be able to access other users' private information or orders without authorization.

NFR-004 — Reliability: Order creation, payment processing, and fulfillment transitions must be designed to prevent duplicate or inconsistent operations.

NFR-005 — Maintainability: New marketplace functionality should reuse the existing architecture and avoid unnecessary dependencies or duplicated components.

NFR-006 — Performance: Product listings and product details should load without unnecessary full-catalog queries or excessive image downloads. Performance shall be measured against a documented test dataset.

NFR-007 — Recoverability: The application, database, and product assets must have a documented backup and recovery process.

NFR-008 — Compatibility: Existing supported browsers and mobile layouts shall continue to work after migration.

NFR-009 — Secrets management: Credentials, payment secrets, and private configuration shall not be committed to the source repository.

NFR-010 — Observability: Errors in checkout, fulfillment, and administrative operations shall be recorded without unnecessarily logging sensitive information.

8. MVP acceptance criteria

The MVP shall be considered functionally complete only when the following scenarios pass.

Catalog and migration

Existing avatar products and assets are preserved or migrated correctly.

Visitors can browse, search, and filter published products.

Product pages display accurate prices, product types, and seller attribution.

Digital, physical, and commission listings can be represented.

Seller workflow

A user can apply for seller access or be added by an administrator.

An administrator can approve a seller.

An approved seller can submit and edit their own listings.

Pending listings remain hidden from the public catalog.

An administrator can publish or reject a listing.

Sellers cannot edit other sellers' listings.

Purchasing and fulfillment

A customer can add an eligible product to the cart.

The server validates product availability and calculates the purchase total.

A successful test payment creates a correctly recorded paid order.

A failed or canceled payment does not release paid digital content.

An authorized purchaser can access their digital product.

Physical inventory and fulfillment status update correctly.

Customers and sellers see only the order information they are authorized to access.

Administration and reliability

Administrators can manage sellers, listings, and order status.

Reported content can be reviewed and moderated.

Important administrative actions are recorded.

Core workflows pass automated or documented end-to-end tests.

Existing storefront functionality has no unresolved critical regressions.

The application can be restored from a tested backup.

If payment-provider integration is intentionally deferred, checkout and real purchases are not complete MVP features. In that case, the first milestone must be described as a catalog and seller-submission pilot, not a fully transactional marketplace.

9. Suggested implementation order

Audit and back up the existing avatar-store project.

Identify reusable components and document the existing data model.

Generalize the product model while preserving avatar listings.

Update branding, navigation, categories, and product pages.

Implement seller profiles and listing submission.

Implement administrative listing approval and moderation.

Implement order, payment, and fulfillment workflows.

Add security, accessibility, migration, and regression tests.

Run a small private pilot with approved sellers.

Resolve pilot issues before public launch.

10. Assumptions and unresolved decisions

The following details must be confirmed against the existing project or decided before the relevant implementation begins:

Existing frontend framework and backend architecture.

Database technology and current product schema.

Authentication and account-management implementation.

Existing cart and payment-provider capabilities.

Whether seller payouts will be automated at launch.

Whether a cart may contain products from multiple sellers.

Whether commissions are purchased directly or begin with a request-and-quote workflow.

Which shipping regions the marketplace will support.

Whether the marketplace will charge seller fees or retain a commission.

Which staff members will have administrative and moderation permissions.

These decisions should be resolved using the smallest implementation that satisfies the MVP, rather than adding infrastructure without a demonstrated need.

11. Definition of success

Barkly Community Market succeeds at the MVP stage when the existing avatar-store foundation has been preserved, multiple product types can be listed, approved sellers can manage their products, customers can complete the supported purchasing workflow, and administrators can safely oversee the marketplace.

The implementation should leave the project ready for future community growth without requiring a complete rewrite.

Guiding principle: Reuse what works, make the missing pieces explicit, and front-load complexity for the people using the marketplace.