# Maize Market Price System

## What the system does

Harvest collects daily maize prices from market centres across Uganda. Field agents sign in, choose any active market centre and enter the maize price per kilogram. The system calculates market-centre, district and Uganda averages from the submitted prices. The public price page displays those averages as a price chart and tables.

## User access

- An administrator creates user categories and chooses which modules each category can access.
- The administrator creates users and places each user in a category. Users can only open modules enabled for their category.
- The administrator manages districts, areas, market centres and commodities. Agents can choose any active market; they do not need market assignments.
- Agents can enter today's prices until 12:00 PM Kampala time. A saved price is included in the averages automatically.
- Users with the buying-prices module can set the official buying price and an optional selling price. These prices appear separately from the agent-reported averages.

## Main workflow

```mermaid
flowchart LR
    A[Administrator sets up categories and modules] --> B[Administrator creates users and markets]
    B --> C[Agent selects a market and submits maize price per kg]
    C --> D[System calculates market, district and national averages]
    D --> E[Public page displays chart and price tables]
    B --> F[Authorized user sets buying and optional selling price]
    F --> E
```

## Data and calculations

Each price is stored with its agent, market centre, commodity, reporting date, price and unit. The reporting screens use kilograms and accept entries only before noon Kampala time. Average prices are calculated from the accepted entries; the public view does not require a separate publish or approval step. Buying and selling prices are stored separately so they are not mixed into reported market averages.

The market hierarchy is district → area/town → market centre. Market-centre averages use agent reports for that centre. District and national averages aggregate the reports in their locations. The chart and tables use the same calculated figures.
