Internal IT tool

Entities (3)

These are the persistent business objects. Field-level annotations (`phi`, `pci_scope`, `eu_pii`) drive the compliance overlay decisions.

Process flows (2)

Capabilities + integrations

• auth.universalproduction
• rbac.tier-2production
• audit.append_onlyproduction
• search.fulltextproduction
• reporting.exportproduction
• security.policiesproduction

Integrations: Slack · GitHub · PagerDuty

Architecture brief

# Internal IT tool reference architecture

## Who this is for

Mid-to-large companies building their own ticket / request / approval
tools instead of paying Zendesk or ServiceNow. Custom-role RBAC,
approvals chained to tickets, Slack notifications, scheduled CSV
exports for audit.

## What's in scope

- **Ticket queue** — title / body / priority / status / assignee.
  Searchable across title + body via the G03 search infra
  capability.
- **Approval requests** — chained off tickets; auditable per-row.
- **Role + custom permissions** — Role.permissions is a JSON map;
  RBAC tier-2 capability picks it up so the gate enforces
  per-permission grants.
- **Slack notifications** — when a ticket is opened / status
  changes, the workflow generator emits the Slack notify step.
- **GitHub integration** — link tickets to PRs / commits.
- **Scheduled reports** — `reporting.export` capability emits the
  G04 report orchestrator + scheduler. Daily / weekly CSV emails
  out the queue stats are one cron entry.

## Compliance bundles produced

- **SOC2**: full bundle from C03 (control matrices, 4 policies,
  access review runbook with the `Ticket` + `ApprovalRequest`
  tables surfaced as audit-required entities, vendor management
  register, evidence calendar).

## Build-time savings

| Build path | Time |
|---|---|
| Manual build by an internal IT team | 6-12 weeks |
| Off-the-shelf (Jira / ServiceNow) | infinite recurring license cost |
| Archiet from this reference architecture | 5-15 minutes |

## How to use

1. Clone to your workspace.
2. Add your domain's role definitions (`Role.permissions` is a free-
   form JSON map; encode whatever permission grant schema your team
   uses).
3. Generate. The reporting.export + search.fulltext + audit.append_only
   capabilities produce the report scheduler + search infrastructure
   + audit chain automatically.
4. Replace the Slack integration if you're a Microsoft Teams shop;
   the workflow step is named the same way regardless of vendor.

## What's NOT in this reference

- LDAP / Active Directory user sync — common for enterprise IT.
  Layer the auth.universal capability's SAML/OIDC providers and
  point them at your IdP.
- Custom workflow designer UI — generated app has the workflow
  flows hard-baked. If your customers need to design their own,
  layer the workflow_generator's runtime variant.