# Gitea Organizational Structure and Conventions

**Last Updated:** 2026-02-10  
**Status:** Active Documentation  
**Gitea Instance:** https://gitea.d-bis.org  
**Primary Org:** d-bis

---

## 1. Overview

Gitea uses a flat model: **Organization → Teams → Users**. This document defines conventions for virtual hierarchy via labels, team naming, and repository organization to support flexible structuring beyond the built-in flat model.

---

## 2. Label-Based Virtual Hierarchy (Option A)

Use repository labels to create virtual groups without code changes.

### 2.1 Project Labels

| Label | Purpose | Example Repos |
|-------|---------|---------------|
| `project/sankofa` | Sankofa Phoenix platform and marketplace | sankofa, as4-411 |
| `project/omnis` | OMNIS application | omnis |
| `project/proxmox` | Proxmox infrastructure and docs | proxmox |
| `project/dbis_core` | DBIS core libraries and services | dbis_core |
| `project/chain138` | Chain 138 blockchain (Besu, RPC, etc.) | smom-dbis-138, rpc-translator-138 |
| `project/explorer` | Blockscout, explorers | explorer-monorepo |
| `project/miracles_in_motion` | MIM web and API | miracles_in_motion |
| `project/the_order` | Order service | the_order |
| `project/virtual-banker` | Virtual banker (voice/TTS, widget) | virtual-banker |

### 2.2 Domain Labels

| Label | Purpose | Example Repos |
|-------|---------|---------------|
| `domain/blockchain` | Blockchain, smart contracts, RPC | smom-dbis-138, alltra-lifi-settlement |
| `domain/web` | Web apps, portals, frontends | miracles_in_motion, omnis |
| `domain/infrastructure` | Proxmox, scripts, configs | proxmox, smom-dbis-138-proxmox |
| `domain/api` | Backend APIs | dbis_core, the_order |

### 2.3 Label Format Convention

- **Project labels:** `project/<name>` — groups repos by product/project
- **Domain labels:** `domain/<name>` — groups repos by technical domain
- Use lowercase, hyphens for multi-word: `project/sankofa-phoenix`

### 2.4 Applying Labels

1. **Create org-level labels:** Run `GITEA_TOKEN=xxx bash scripts/dev-vm/apply-gitea-labels.sh` (includes `project/virtual-banker`).
2. Repo Settings → Labels — add relevant `project/*` and `domain/*` labels to each repo (e.g. **virtual-banker**: `project/virtual-banker`, `domain/api`).
3. Filter repos by label in Gitea UI or API

---

## 3. Team Naming Conventions

### 3.1 Format

`org-d-bis/team-<role>` or `org-d-bis/team-<project>-<role>`

### 3.2 Example Teams

| Team Name | Purpose |
|-----------|---------|
| `team-frontend` | Frontend developers |
| `team-backend` | Backend developers |
| `team-infra` | Infrastructure, DevOps |
| `team-sankofa` | Sankofa/Phoenix maintainers |
| `team-blockchain` | Chain 138, Besu, RPC maintainers |

### 3.3 Permissions

- **Owners:** Full org control
- **Admins:** Repo admin, branch protection
- **Writers:** Push, PR merge
- **Readers:** Pull, read-only

---

## 4. Target Hierarchy (Design)

Planned virtual structure for filtering and reporting:

```
d-bis (org)
├── project/sankofa
│   ├── sankofa (main repo)
│   └── as4-411 (marketplace submodule)
├── project/omnis
│   └── omnis
├── project/proxmox
│   └── proxmox
├── project/chain138
│   ├── smom-dbis-138
│   ├── rpc-translator-138
│   └── smom-dbis-138-proxmox
├── project/explorer
│   └── explorer-monorepo
├── project/virtual-banker
│   └── virtual-banker
└── domain/*
    └── (repos tagged by domain)
```

---

## 5. Option B: Multiple Orgs (Medium Term)

If separation is needed:

| Org | Purpose | Repos |
|-----|---------|-------|
| `d-bis` | Main, shared | proxmox, dbis_core |
| `d-bis-sankofa` | Sankofa Phoenix | sankofa, as4-411 |
| `d-bis-infra` | Infrastructure | smom-dbis-138-proxmox, configs |
| `d-bis-apps` | Applications | omnis, miracles_in_motion, the_order |

Requires Keycloak/SAML/LDAP for cross-org identity.

---

## 6. Option C: Subgroups (Long Term)

Track Forgejo/Gitea PR [#35295](https://github.com/go-gitea/gitea/pull/35295) for native subgroups. Target hierarchy:

- `d-bis / sankofa / marketplace`
- `d-bis / blockchain / chain138`
- `d-bis / apps / omnis`

---

## 7. References

- [DEV_VM_GITOPS_PLAN.md](DEV_VM_GITOPS_PLAN.md) — Dev VM and Gitea setup
- [AS4_411_PHOENIX_SUBMODULE_AND_PUSH_ALL.md](AS4_411_PHOENIX_SUBMODULE_AND_PUSH_ALL.md) — Sankofa marketplace
- [Gitea Organizations](https://docs.gitea.com/usage/organizations)
- [Gitea Labels](https://docs.gitea.com/usage/labels)