> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Portfolios

> Group units across blocks and branches for reporting, ownership and assignment.

**Portfolios → `/portfolios`**

A portfolio is a named group of units that cuts across the physical hierarchy. Where a block
answers "which building is this unit in?", a portfolio answers "which set of units do we manage
together?" — an owner's holdings, a fund's assets, a manager's patch, a scheme's inventory.

## What a portfolio holds

| Section               | Fields                                                     |
| --------------------- | ---------------------------------------------------------- |
| **Identity**          | Name, code, description, kind, category, colour            |
| **Ownership & dates** | Owner / landlord, effective start date, effective end date |
| **Membership**        | Assigned units                                             |
| **Status**            | Active or inactive                                         |
| **Notes**             | Internal notes, not visible to owners                      |

**Code** is required and should be short and stable — it is what appears in exports and reports.
**Colour** gives the portfolio a consistent visual identity across grids and charts.

## Effective dates

A portfolio has a start date and an optional end date; leaving the end date blank makes it
open-ended. Dating a portfolio matters when holdings change hands: a fund that acquired units in
March should not appear to have owned them in January.

## Creating a portfolio

<Steps>
  <Step title="New portfolio">
    Name, code, kind and category. Choose the kind that reflects why the group exists — ownership,
    management, or reporting.
  </Step>

  <Step title="Set ownership">
    Attach the owner or landlord if the portfolio represents someone's holdings.
  </Step>

  <Step title="Set effective dates">
    Start date at minimum; leave the end open unless you know when it closes.
  </Step>

  <Step title="Assign units">
    Add the member units. A unit can belong to more than one portfolio — one for ownership, one for
    the manager's patch.
  </Step>

  <Step title="Save">
    The portfolio becomes available as a filter and grouping across the platform.
  </Step>
</Steps>

## Using portfolios

| Use            | How                                                                                            |
| -------------- | ---------------------------------------------------------------------------------------------- |
| **Reporting**  | Filter or group financial and occupancy reports by portfolio to see a set of units as a whole. |
| **Ownership**  | Represent an owner's holdings without changing which block a unit physically sits in.          |
| **Assignment** | Give a manager a patch that spans blocks.                                                      |
| **Comparison** | Compare performance across portfolios — occupancy, arrears, revenue per unit.                  |

## Portfolios vs blocks vs branches

| Concept       | Nature                               | Can a unit belong to more than one? |
| ------------- | ------------------------------------ | ----------------------------------- |
| **Branch**    | Operating scope; controls visibility | No                                  |
| **Block**     | Physical location                    | No                                  |
| **Portfolio** | Logical grouping                     | Yes                                 |

Branch is the security and scoping boundary. Block is geography. Portfolio is how *you* choose to
think about the estate — and it is the only one of the three you can freely re-cut without moving
anything.

## Maintaining portfolios

* **Review membership quarterly.** Units acquired or disposed of drift out of date quickly.
* **Close rather than delete.** Set an end date so historical reporting stays correct.
* **Keep codes stable.** Renaming is safe; re-coding breaks saved exports and downstream
  spreadsheets.

## Next steps

<Columns cols={2}>
  <Card title="Units" icon="door-closed" href="/guides/units">
    The members of a portfolio.
  </Card>

  <Card title="Owners & landlords" icon="user-tie" href="/guides/owners-landlords">
    Ownership-based grouping and reporting.
  </Card>
</Columns>