Softech designed and continues to develop KILOGRAM as a live agricultural marketplace ecosystem combining a mobile application, web platform, central API and administration panel. The system separates SELL and BUY flows and supports search, profiles, favourites, documents, paid promotion, notifications, community features, moderation and AI-assisted listing descriptions and imagery. A TypeScript architecture using React Native, NestJS, PostgreSQL, Redis and BullMQ maintains one domain model across all channels and gives operators control over queues, generation attempts, errors and statuses without involving engineers in every daily operation. This project overview documents confirmed product capabilities and intentionally excludes unapproved growth, conversion and user-count data.
Business context and the situation before implementation
Agricultural trade takes place across phone calls, messaging applications, social groups, local listing sites and direct relationships. KILOGRAM was created as specialised digital infrastructure that organises supply and demand without forcing users to abandon fast, mobile-first working habits.
- Sellers need fast publishing with product, quantity, unit, location, imagery and commercial terms.
- Buyers need to publish demand and filter the market by product, variety, quantity, unit and region.
- Platform operators need one place for moderation, user support, paid promotion, documents, errors and AI workflows.
- The product must remain consistent across mobile, web and administration surfaces even though each channel has different UX requirements.
- The business model needs room for additional monetisation and distribution channels without rebuilding the core listing workflow.
Before state
Before a unified product existed, trading and publishing workflows were fragmented across channels and supply and demand information did not form a consistent data model. Launching another basic listing website would not solve the problem because operations tooling, AI controls, monetisation and cross-channel consistency would still be missing.
- Supply and purchase demand were communicated in similar ways even though they require different forms, messaging and filters.
- Publishing a strong listing required users to prepare the description and visual material themselves.
- Moderation and error investigation lacked a single auditable operational centre.
- Paid promotion, documents, notifications and statuses needed to work as one process rather than unrelated add-ons.
- Unstable mobile connectivity could cause repeated actions, unclear feedback and loss of user trust.
Goals, success criteria and constraints
Discovery began by mapping actors, listing states and actions that needed to remain shared across every channel. Instead of designing the app, website and administration panel independently, the team defined central domain rules and then adapted interfaces to the seller, buyer, moderator and administrator contexts.
Product goals
- Create one domain model supporting separate SELL and BUY workflows.
- Provide complete user journeys in both the mobile application and web platform.
- Give operators independent control over moderation, statuses, payments, documents and AI processes.
- Introduce controlled AI that reduces listing preparation effort without automatically publishing unreviewed output.
- Prepare the foundation for paid promotion, additional monetisation models, more languages and external publishing channels.
- Preserve observability and resilience for asynchronous processes requiring retries, idempotency and attempt history.
Success criteria
- The same listing and user state are interpreted consistently by mobile, web, API and administration surfaces.
- Users understand from the beginning whether they are publishing supply or purchase demand.
- The AI process records status, prompt version, provider, attempts and errors and can be retried safely.
- Operators can perform daily moderation and operational tasks without direct database intervention.
- Paid promotion and documents have consistent statuses visible across user and operational channels.
- New modules can be added without copying domain logic into multiple independent clients.
Multiple clients, one domain state
Mobile, web and administration surfaces have different interactions but must use the same permission, validation and status rules.
Mobile connectivity
Critical actions must communicate network state clearly, avoid accidental duplication and recover safely from interrupted workflows.
Asynchronous processes
AI generation, notifications and integration work must not block the interface or disappear without status and error history.
AI quality control
The system must resolve product domains, limit incorrect fallbacks and preserve retry, rejection and manual review paths.
Evolution without stopping the product
New features, data migrations and model changes must be introduced iteratively in a live production system.
Multilingual content
Interface, listing, operational and supporting content must remain semantically consistent in Polish and English.
Analysis and product decisions
- Separate SELL and BUY as distinct user intentions rather than one form with an additional field.
- Define the lifecycle of a listing, promotion, payment, document and moderation process.
- Determine which rules belong in the backend and which are presentation concerns for mobile or web.
- Design operational tools before scaling the number of AI and moderation processes.
- Separate synchronous actions from jobs requiring queues, retries, attempt history and idempotency controls.
- Adopt the principle that AI assists publishing but does not replace the domain model or user and operator responsibility.
Solution architecture
KILOGRAM uses a layered architecture: separate user experiences consume a central API while resilience-sensitive work runs outside the request-response cycle. Marketplace, payment, moderation and AI rules therefore do not need to be copied across multiple clients.
- 01Experience layer
Mobile application and web platform
Dedicated interfaces for fast mobile actions, notifications, listing discovery, publishing and indexable web pages.
React NativeExpoReactNext.jsTypeScript - 02Operations
Administration panel
Operational centre for users, listings, reports, moderation, configuration, payments and AI processes.
ReactTypeScriptRole-based access - 03Domain and API
Central backend
Authentication, SELL/BUY rules, validation, statuses, payments, documents, notifications, community features and integrations.
NestJSTypeScriptREST API - 04Data
Transactional model
Relational model for users, listings, promotions, payments, documents, discussions, reports and state history.
PostgreSQLPrisma - 05Asynchronous processing
Queues and workers
Controlled execution of AI generation, notifications, translations, moderation and other jobs requiring retries and observability.
RedisBullMQBackground workers - 06Delivery
Infrastructure and edge
Separated environments for frontend and backend services, traffic protection, caching, health checks and production monitoring.
VercelRenderCloudflare
Problems, decisions and implemented capabilities
Supply and purchase demand require different data and messaging.
Separate SELL and BUY at the domain-model and interface levels.
Dedicated publishing, validation, presentation and filtering flows.
Users communicate the correct intention from the beginning and the system can evolve rules for both market sides independently.
Mobile and web could diverge in statuses and permissions.
Keep business rules in the central API instead of duplicating them in clients.
Shared authentication, validation, listing lifecycle and data model.
Each channel can evolve its own UX without changing the meaning of domain operations.
Preparing descriptions and imagery increases publishing friction.
Add AI as a controlled assistance layer rather than an autonomous publisher.
Description and image generation with domain data, prompt versions, attempt history, retries and operator control.
Users receive content assistance while the platform preserves audit and rejection paths for incorrect output.
Daily operations cannot depend on manual engineering intervention.
Design the administration panel as an operational tool rather than a data viewer.
Moderation, reports, statuses, configuration, AI controls, queues, errors and retries.
Operators can handle most repeatable situations independently and diagnose exceptions faster.
Listing monetisation affects payments, visibility, documents and communication.
Treat promotion as a complete domain process with its own statuses.
Paid promotion, status synchronisation, documents and promotion presentation across mobile, web and administration.
The revenue model can evolve without inconsistency between payment and actual listing visibility.
Deleting content can destroy relationships needed for audits and reports.
Use moderation states and soft deletion where preserving context matters.
Visibility restriction while preserving history, relationships and discussion context.
The operations team can investigate events without reconstructing deleted data.
Technology decisions
| Technology | Role | Rationale | Trade-off |
|---|---|---|---|
| TypeScript | Shared language across mobile, web, backend and operational tooling. | Reduces contract drift, supports type reuse and enables controlled refactoring in an evolving product. | Requires type discipline and explicit boundaries between server and client code. |
| React Native + Expo | Dedicated mobile application for iOS and Android. | Supports one mobile product with access to notifications, biometrics and native distribution mechanisms. | Operating-system-specific features still require separate configuration and testing for both platforms. |
| Next.js / React | Web platform and indexable browser experience. | Combines an application-like interface with SSR/SSG, metadata and URLs useful for content discovery, SEO and visibility in AI systems. | Requires deliberate control of data boundaries, bundles and hydration consistency. |
| NestJS | Central API and domain modules. | Its modular structure supports clear responsibilities for listings, users, payments, documents, moderation and AI. | A growing system requires disciplined module boundaries and control of hidden service dependencies. |
| PostgreSQL + Prisma | Transactional data model and schema migrations. | Relationships between users, listings, promotions, payments, documents and discussions require consistency and controlled migrations. | Model changes in a live product require compatibility planning and safe data migrations. |
| Redis + BullMQ | Queues, retries and asynchronous processing. | Separates expensive or failure-prone work from user requests and enables attempt and status control. | Introduces additional operational state that must be monitored, idempotent and recoverable. |
Integrations and data flows
Payment provider
bidirectionalAuthorise paid promotion and preserve consistency between the transaction, promotion status and document.
The backend validates statuses, stores process results and handles cases in which users return from payment in an unexpected state.
Notification services
outboundInform users about status changes, activity and events requiring action.
Events are separated from the user interface so delivery failure does not need to block the main operation.
OpenAI API and model layer
request / resultAssist description and image generation using structured listing data.
Calls are versioned, queued and stored as attempts; incorrect output can be rejected or retried.
External publishing channels
outboundExtend distribution of selected listings and content beyond the platform's owned channels.
Publishing is treated as a separate status-driven process with error handling rather than an uncontrolled side effect of saving a listing.
Cloudflare / edge layer
inbound trafficTraffic protection, DNS control, caching and stable routing to web and API layers.
Edge configuration is separated from product code and governed by its own caching, domain and crawler rules.
AI, security and reliability
The AI layer is a domain process with inputs, state, validation and operational control. The model does not receive an unrestricted user prompt and does not publish output directly. Listing data is transformed into a versioned prompt and each attempt leaves a trace for diagnosis, retry or rejection.
AI workflow
- Collect structured product, listing-type, category, location and publishing data.
- Resolve the product domain and archetype and select the appropriate prompt version.
- Create a queued job with an identifier, model, provider and configuration version.
- Run generation outside the main user request.
- Validate output for required fields and domain consistency.
- Store result, error and attempt history and expose retry or rejection to operators.
Controls
- Prompt, provider and model versioning for each attempt.
- Domain rules that block incompatible archetypes and incorrect fallbacks.
- Queues, retries, statuses and idempotency controls for failure-prone jobs.
- Administration-panel attempt and error history for diagnosis without direct production-database access.
- Manual rejection of output while preserving the previous content version.
- Separation of AI description, AI image and moderation processes into distinct responsibilities.
Limitations
- AI assists users but does not replace data validation or responsibility for final publication.
- Output quality depends on the completeness and correctness of listing inputs.
- New domains and unusual products require archetype testing and rule updates before production use.
- The project overview does not attribute conversion or publishing-time improvements to AI without approved analytics measurement.
- Controls reduce errors but do not make a generative model deterministic.
Authentication and sessions
User access is protected through OTP, session management and mobile mechanisms including biometrics where available.
Operational permissions
Roles and permissions restrict access to moderation, administration, configuration and actions affecting other users' state.
History and soft deletion
Content removal can restrict visibility without destroying relationships needed for audits, reports and context preservation.
Resilient asynchronous jobs
Statuses, retries and attempt history distinguish queued, completed, rejected and intervention-required jobs.
Health checks and monitoring
Production layers are observed through health checks, service logs and alerts required to diagnose infrastructure and integration failures.
Network-aware error communication
The interface distinguishes connectivity failures from domain errors so users know whether to retry, correct data or wait.
Implementation, testing and release
- 1Phase 1 — Discovery and domain model
Define actors, SELL/BUY intentions, listing lifecycle and system responsibility boundaries.
- Role and journey map
- Listing and moderation state model
- MVP scope and module sequence
- Contracts between clients and API
Result: One product definition that allowed mobile, web, backend and administration work to progress in parallel.
- 2Phase 2 — Platform foundations
Launch secure access, central data and core publishing and discovery flows.
- Authentication and profiles
- React Native application
- Web platform
- NestJS API and PostgreSQL
- Search, filters, favourites and listing details
Result: A working multi-channel marketplace using one data model and set of domain rules.
- 3Phase 3 — Operations and monetisation
Give operators platform-management tools and implement revenue-generating processes.
- Administration panel
- Moderation and reports
- Paid promotion
- Documents and payment statuses
- Notifications and community features
Result: Daily operations and core monetisation became part of the same controlled product workflow.
- 4Phase 4 — Production AI
Reduce publishing friction without losing control over generation quality and state.
- AI descriptions and AI images
- Domain archetypes and prompts
- Queues and retries
- Attempt and version history
- Administration controls and mismatch handling
Result: AI became an observable system module rather than an uncontrolled call from the user interface.
- 5Phase 5 — Stabilisation and evolution
Maintain production quality while adding modules, integrations and domain variants.
- Monitoring and health checks
- Critical-flow regression coverage
- Web and mobile optimisation
- Moderation and trust-and-safety evolution
- Search and AI-system visibility, localisation and new channels
Result: The platform can evolve iteratively without replacing its foundations for every new feature.
Type and build gates
Mobile, web and API pass TypeScript validation and production builds before changes affecting shared contracts are released.
Critical-flow regression checks
SELL, BUY, AI, payment, document and moderation paths are checked for changes that could break existing user or data state.
Failure and retry testing
Asynchronous processes are also tested for timeouts, invalid responses, retries and states requiring operator intervention.
Cross-channel QA
Domain-rule changes are verified across mobile, web and administration because defects may surface in a different channel than the implementation.
Observable rollout
After release, service logs, health checks and job statuses are used to identify integration failures and production regressions.
Production-compatible migrations
Database and model changes are planned so live clients do not receive an incompatible contract during deployment.
What confirms the project description
The description includes only features, relationships and decisions that can be confirmed in the live product, system documentation, interfaces or operational workflows. Growth data will be added only when a reference point, measurement period, source and data owner can be identified.
| Scope | Basis | Reference | Confirmation | Interpretation boundary |
|---|---|---|---|---|
| KILOGRAM operates as a system spanning a mobile application, web platform, central API and administration panel. | Implemented product scope | KG-01 · KILOGRAM production architecture and modules | Confirmed in the product | The statement describes product scope, not active-user volume. |
| The marketplace separates SELL and BUY listings as distinct domain flows. | Domain model | KG-02 · Listing forms, validation, statuses and presentation | Confirmed in the product | The evidence does not state the market share of each listing type. |
| The AI layer assists listing description and image generation and stores attempt history. | Product functionality | KG-03 · AI Description, AI Images, queues and operational panel | Confirmed in the product | No time or conversion impact is published without approved measurement. |
| AI jobs and other asynchronous processes use Redis, BullMQ and retry mechanisms. | Solution architecture | KG-03 · Queue, worker and job-status configuration | Confirmed in the product | The project overview does not publish job volume or failure rate. |
| The platform supports paid listing promotion and associated documents. | Business process | KG-04 · Promotion, payment, status and document modules | Confirmed in the product | Promotion revenue and conversion are not published without financial data. |
| The administration panel enables moderation, AI control, error analysis and retry of selected processes. | Operational tools | KG-04 · Administration views and operational endpoints | Confirmed in the product | Available actions depend on the operator role. |
| The system uses soft deletion and moderation states to preserve selected relationship context. | Data model and moderation | KG-04 · Listing, discussion, report and visibility-state relationships | Confirmed in the product | Retention depends on data type and is not presented as universal for every record. |
| KILOGRAM includes Polish and English language layers across its evolving product channels. | Product localisation | KG-01 · Application, web and system-content i18n resources | Confirmed in the product | This does not automatically indicate an operational launch in every English-speaking market. |
How to read this information
- Confirmation of a feature means it exists in the product; it does not automatically prove an effect on revenue, conversion or retention.
- User, listing, transaction and revenue counts are not published without an approved analytics or financial source.
- Qualitative outcomes describe process changes and available tools rather than statistical causality.
- After GSC, GA4 and product analytics are connected, the material can be extended with before-and-after comparisons.
- Every future metric must identify its source, period, update date and interpretation boundary.
Process change, decision consequences and lessons
| Area | Before | After | Business impact |
|---|---|---|---|
| Market structure | Supply and demand were fragmented across channels without a shared data model. | SELL and BUY operate in one marketplace while preserving distinct publishing and filtering rules. | The platform can organise both market sides and evolve separate discovery mechanisms for each. |
| Product channels | Users relied on multiple inconsistent tools and communication methods. | Mobile and web share the same API, profile, data and listing states. | A new channel can evolve without creating a separate operational system. |
| Content preparation | Descriptions and imagery depended entirely on user time, knowledge and source material. | AI assists content preparation through a controlled process with attempt history and rejection paths. | The platform reduces publishing friction without abandoning quality control. |
| Operations | Exceptions and problems would require frequent engineering involvement or manual data analysis. | The panel exposes statuses, reports, attempts, errors and recovery actions to authorised operators. | Daily operation is less dependent on engineers and exceptions have a clearer diagnostic trail. |
| Monetisation | Listing promotion could be only a visual marker without a complete payment and document process. | Promotion has its own lifecycle connected to payment, visibility, status and documentation. | The platform has a foundation for controlled paid products and status reporting. |
| Process resilience | Expensive synchronous operations could block users and lose state after failure. | Resilience-sensitive work uses queues, statuses, retries and attempt history. | Failures can be diagnosed and recovered without repeating the entire user workflow. |
Separate mobile and web clients with a shared API
- Alternative
- One universal web application used in every context.
- Trade-off
- Two interfaces require separate QA and release coordination.
- Rationale
- Mobile needs notifications, biometrics and fast actions, while web needs indexability, desktop usability and public discovery.
Queues for AI and integrations
- Alternative
- Run generation directly inside the user request.
- Trade-off
- Queues add their own state, monitoring and retry scenarios.
- Rationale
- The user flow remains responsive and provider failure does not erase job history or force data re-entry.
AI assistance instead of automatic publishing
- Alternative
- Fully automated content without a review step.
- Trade-off
- A user or operator still makes the final decision.
- Rationale
- Commercial data and product representation require control and generative models are not deterministic.
Soft deletion for contextual data
- Alternative
- Immediate permanent deletion of every record.
- Trade-off
- The data model and queries must consistently account for visibility state.
- Rationale
- Moderation, reports and discussions require preserving relationships needed for audits and investigation.
Modular evolution of a live product
- Alternative
- One-time delivery of a complete fixed specification.
- Trade-off
- Architecture, migrations and tests must account for continuous change.
- Rationale
- The marketplace evolves with user data, operations, monetisation and new domain cases.
Key lessons learned
- In a B2B marketplace, SELL and BUY intent should exist in the domain rather than only in an interface label.
- Administration tooling should be designed alongside the user product because missing operational tools quickly become a scaling constraint.
- Production AI requires versioning, statuses, attempt history and a manual path; a prompt alone is not product architecture.
- Payment for listing visibility is a process spanning transaction, entitlement, document and communication rather than one button.
- A multi-channel product needs central status semantics because the same record is presented differently in mobile, web and administration.
- Data-source quality should be established before publishing KPIs in marketing and expert materials.
Which organisations this model is relevant for
Two-sided B2B marketplaces
Organisations that need separate supply and demand models within one discovery, communication and operations system.
Vertical platforms with mobile applications
Products requiring fast mobile UX, public web discovery, shared profiles and central domain rules.
Products monetising visibility or priority
Systems in which paid promotion must remain consistent with payment, documentation, entitlement and actual content exposure.
Organisations implementing controlled AI
Teams that want content or media generation with domain constraints, retries, auditability and administration quality controls.
Platforms requiring moderation and trust and safety
Community products and marketplaces in which reports, states, soft deletion and event history are operational requirements.
Companies evolving one product across multiple channels
Organisations needing separate mobile and web clients without duplicating business and integration logic.
Related expertise and services
Mobile app development
Design and development of production React Native applications connected to central backends and operational workflows.
Web application development
Web systems combining user interfaces, APIs, roles, data, payments, integrations and administration tooling.
AI automation and systems
Controlled AI processes with queues, observability, fallbacks, validation and human intervention paths.
Marketplace and eCommerce development
Architecture for transactions, catalogues, discovery, payments, promotion, documents and commercial operations.
React Native
Mobile application technology sharing domain and API foundations with the web platform.
Node.js and NestJS
Modular APIs, asynchronous processing, integrations and business-system logic.
Foodeli — last-mile logistics
A related example of multiple roles, mobile applications and an operational platform serving a two-sided market.
How we built the KILOGRAM ecosystem
A supporting article expanding the project overview with product-development and delivery-stage context.
Planning a platform that connects multiple channels and operational workflows?
Discuss the domain model, architecture, mobile, web, monetisation, operational tooling and controlled AI layer before expensive decisions become embedded in code.
Key confirmed facts
The following statements summarise the confirmed product scope and contain no unapproved growth data.
- 1
Softech designed and continues to develop KILOGRAM as a live marketplace platform for agricultural trade.
- 2
KILOGRAM combines a mobile application, web platform, central backend API and administration panel.
- 3
The KILOGRAM platform separates SELL and BUY listings as distinct domain workflows.
- 4
The KILOGRAM mobile application and web platform use the same data model and central API rules.
- 5
KILOGRAM supports paid listing promotion and associated payment statuses and documents.
- 6
The KILOGRAM AI layer assists listing description and image creation using structured product data.
- 7
KILOGRAM AI processes store the prompt version, provider, model, status and attempt history.
- 8
KILOGRAM uses Redis and BullMQ for jobs requiring queues, retries and observability.
- 9
The KILOGRAM administration panel supports moderation, status control, error analysis and selected AI operations.
- 10
KILOGRAM uses PostgreSQL and Prisma for relational user, listing, promotion, document and operational data.
- 11
KILOGRAM includes Polish and English language layers across its evolving product channels.
- 12
Softech is responsible for KILOGRAM product strategy, UX/UI, mobile, web, backend, AI, infrastructure and continued system development.
- 13
The KILOGRAM project overview does not publish unapproved user-count, revenue or conversion data.
- 14
KILOGRAM is developed iteratively as a live production system rather than a one-time prototype.
Visual evidence
The diagrams present confirmed product scope and workflows described in this material. They are not mock-ups or claims of undocumented outcomes.
FAQ
Why does KILOGRAM need both a mobile app and a web platform?
Mobile supports frequent actions and push notifications, while the web increases accessibility, enables indexable listing pages and provides a convenient desktop experience. Both surfaces use the same API and domain model.
How does the platform distinguish selling from purchase demand?
SELL and BUY are separate domain flows with their own messaging, validation and presentation. Users define from the beginning whether they are offering a product or publishing demand.
How is AI used in KILOGRAM?
AI assists with listing descriptions and images. The system combines product data, domain rules, versioned prompts, attempt history, queues, retries and administration-panel quality controls.
How can operators control incorrect AI generations?
The administration panel exposes status, model, provider, prompt version, attempt history and errors. Operators can retry a job, reject an output or analyse a domain mismatch.
Does the system support paid listing promotion?
Yes. Monetisation includes paid promotion and promotion statuses that must remain consistent across the backend, mobile app, web platform, documents and administration panel.
How are moderation and content deletion handled?
The system combines moderation statuses, reports and soft deletion. This limits or removes visibility without destroying relationships needed for auditability and discussion context.
Can the architecture support additional markets?
The localisation layer, central domain model, separate mobile and web clients and modular infrastructure provide a foundation for more languages, integrations and monetisation models.
