# popxicallab/pop-os architecture

> Architecture diagram of the GitHub repository popxicallab/pop-os, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/popxicallab/pop-os
- Repository: https://github.com/popxicallab/pop-os

## Overview

Pop OS is an internal studio operations system. The principal workflow runs from sales lead management through won-deal/job tracking into project production, capacity allocation, and financial visibility; separate capabilities cover people, skills, staffing, personal journeys, reporting, and notifications. The graph combines documented product flows with source-index references and shown controller calls. Several subsystem implementations were not sampled, so their internal links are omitted rather than inferred.

Main entry points: [`src/projects/projects.service.ts`](https://github.com/popxicallab/pop-os/blob/main/src/projects/projects.service.ts) (Project management), [`src/leads/leads.service.ts`](https://github.com/popxicallab/pop-os/blob/main/src/leads/leads.service.ts) (Sales pipeline), [`src/people/people.service.ts`](https://github.com/popxicallab/pop-os/blob/main/src/people/people.service.ts) (People records), [`src/audit/audit.service.ts`](https://github.com/popxicallab/pop-os/blob/main/src/audit/audit.service.ts) (Audit log)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sales["Sales and Jobs"]
  node_leads["Sales pipeline<br/>[leads.service.ts]"]
  node_accounts["Accounts and contacts"]
  node_jobs["Won deals and jobs<br/>[jobs.service.ts]"]
  node_attachments["Job attachments"]
end

subgraph group_delivery["Project Delivery"]
  node_projects["Project management"]
  node_production["Production lanes"]
  node_capacity["Capacity planning"]
  node_capacitydto["Capacity data contract<br/>[capacity.dto.ts]"]
  node_ppm["PPM rules<br/>[ppm.service.ts]"]
end

subgraph group_people["People and Staffing"]
  node_staffing["Staffing recommendations"]
  node_peopledata["People records<br/>[people.service.ts]"]
  node_skills["Skills and ratings<br/>[skills.service.ts]"]
  node_journey["Personal journey<br/>[me.service.ts]"]
  node_selfassess["Self assessment"]
end

subgraph group_operations["Finance and Insights"]
  node_autocount["Autocount accounting"]
  node_dashboard["Operations dashboard"]
  node_financial["Financial overview"]
  node_performance["Sales commissions"]
  node_audit["Audit log<br/>[audit.service.ts]"]
end

subgraph group_platform["Identity and Notifications"]
  node_auth["Login and access<br/>[auth.service.ts]"]
  node_rules["Notification rules"]
  node_mattermost["Mattermost messaging"]
  node_email["Email notifications"]
  node_roles["Role and money guards<br/>[roles.ts]"]
  node_database[("PostgreSQL via Prisma<br/>[prisma.service.ts]")]
end

node_staff(("Studio user"))

node_staff -->|"signs in"| node_auth
node_staff -->|"manages pipeline"| node_leads
node_leads -->|"converts won lead"| node_projects
node_leads -->|"tracks won deal"| node_jobs
node_leads -->|"creates quotation"| node_autocount
node_projects -->|"creates invoice"| node_autocount
node_jobs -->|"tracks files"| node_attachments
node_jobs -->|"links documents"| node_autocount
node_projects -->|"routes by lane"| node_production
node_projects -->|"allocates weekly capacity"| node_capacity
node_capacity -->|"uses contract"| node_capacitydto
node_projects -->|"requests suggestions"| node_staffing
node_projects -.->|"uses quadrant rules"| node_ppm
node_staff -->|"manages clients"| node_accounts
node_staff -->|"maintains staff records"| node_peopledata
node_peopledata -->|"records skills"| node_skills
node_peopledata -->|"views personal history"| node_journey
node_staff -->|"submits assessment"| node_selfassess
node_staff -->|"views command centre"| node_dashboard
node_staff -->|"reviews finances"| node_financial
node_staff -->|"tracks commissions"| node_performance
node_leads -->|"logs changes"| node_audit
node_projects -->|"logs changes"| node_audit
node_staff -->|"configures messages"| node_rules
node_rules -->|"dispatches messages"| node_mattermost
node_auth -->|"sends reset link"| node_email
node_auth -->|"reads and updates users"| node_database
node_audit -->|"writes and queries logs"| node_database
node_capacity -->|"reads and writes allocations"| node_database
node_peopledata -->|"records changes"| node_audit
node_leads -->|"enforces job access"| node_roles

click node_auth "https://github.com/popxicallab/pop-os/blob/main/src/auth/auth.service.ts"
click node_leads "https://github.com/popxicallab/pop-os/blob/main/src/leads/leads.service.ts"
click node_accounts "https://github.com/popxicallab/pop-os/blob/main/src/accounts/accounts.service.ts"
click node_jobs "https://github.com/popxicallab/pop-os/blob/main/src/jobs/jobs.service.ts"
click node_attachments "https://github.com/popxicallab/pop-os/blob/main/src/job-attachments/job-attachments.service.ts"
click node_autocount "https://github.com/popxicallab/pop-os/blob/main/src/autocount/autocount.service.ts"
click node_projects "https://github.com/popxicallab/pop-os/blob/main/src/projects/projects.service.ts"
click node_production "https://github.com/popxicallab/pop-os/blob/main/src/production/production.service.ts"
click node_capacity "https://github.com/popxicallab/pop-os/blob/main/src/capacity/capacity.service.ts"
click node_capacitydto "https://github.com/popxicallab/pop-os/blob/main/src/capacity/capacity.dto.ts"
click node_ppm "https://github.com/popxicallab/pop-os/blob/main/src/ppm/ppm.service.ts"
click node_staffing "https://github.com/popxicallab/pop-os/blob/main/src/staffing/staffing.service.ts"
click node_peopledata "https://github.com/popxicallab/pop-os/blob/main/src/people/people.service.ts"
click node_skills "https://github.com/popxicallab/pop-os/blob/main/src/skills/skills.service.ts"
click node_journey "https://github.com/popxicallab/pop-os/blob/main/src/me/me.service.ts"
click node_selfassess "https://github.com/popxicallab/pop-os/blob/main/src/self-assess/self-assess.service.ts"
click node_dashboard "https://github.com/popxicallab/pop-os/blob/main/src/dashboard/dashboard.service.ts"
click node_financial "https://github.com/popxicallab/pop-os/blob/main/src/financial/financial.service.ts"
click node_performance "https://github.com/popxicallab/pop-os/blob/main/src/sales-performance/sales-performance.service.ts"
click node_audit "https://github.com/popxicallab/pop-os/blob/main/src/audit/audit.service.ts"
click node_rules "https://github.com/popxicallab/pop-os/blob/main/src/mattermost/notification-rules.service.ts"
click node_mattermost "https://github.com/popxicallab/pop-os/blob/main/src/mattermost/mattermost.service.ts"
click node_email "https://github.com/popxicallab/pop-os/blob/main/src/notifications/notifications.service.ts"
click node_roles "https://github.com/popxicallab/pop-os/blob/main/src/common/roles.ts"
click node_database "https://github.com/popxicallab/pop-os/blob/main/src/prisma.service.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_leads,node_accounts,node_jobs,node_attachments,node_staff toneBlue
class node_projects,node_production,node_capacity,node_capacitydto,node_ppm toneAmber
class node_staffing,node_peopledata,node_skills,node_journey,node_selfassess toneMint
class node_autocount,node_dashboard,node_financial,node_performance,node_audit toneRose
class node_auth,node_rules,node_mattermost,node_email,node_roles,node_database toneIndigo
```

## Components

### Sales and Jobs

- [Sales pipeline](https://github.com/popxicallab/pop-os/blob/main/src/leads/leads.service.ts): `src/leads/leads.service.ts`
- [Accounts and contacts](https://github.com/popxicallab/pop-os/blob/main/src/accounts/accounts.service.ts): `src/accounts/accounts.service.ts`
- [Won deals and jobs](https://github.com/popxicallab/pop-os/blob/main/src/jobs/jobs.service.ts): `src/jobs/jobs.service.ts`
- [Job attachments](https://github.com/popxicallab/pop-os/blob/main/src/job-attachments/job-attachments.service.ts): `src/job-attachments/job-attachments.service.ts`

### Project Delivery

- [Project management](https://github.com/popxicallab/pop-os/blob/main/src/projects/projects.service.ts): `src/projects/projects.service.ts`
- [Production lanes](https://github.com/popxicallab/pop-os/blob/main/src/production/production.service.ts): `src/production/production.service.ts`
- [Capacity planning](https://github.com/popxicallab/pop-os/blob/main/src/capacity/capacity.service.ts): `src/capacity/capacity.service.ts`
- [Capacity data contract](https://github.com/popxicallab/pop-os/blob/main/src/capacity/capacity.dto.ts): `src/capacity/capacity.dto.ts`
- [PPM rules](https://github.com/popxicallab/pop-os/blob/main/src/ppm/ppm.service.ts): `src/ppm/ppm.service.ts`

### People and Staffing

- [Staffing recommendations](https://github.com/popxicallab/pop-os/blob/main/src/staffing/staffing.service.ts): `src/staffing/staffing.service.ts`
- [People records](https://github.com/popxicallab/pop-os/blob/main/src/people/people.service.ts): `src/people/people.service.ts`
- [Skills and ratings](https://github.com/popxicallab/pop-os/blob/main/src/skills/skills.service.ts): `src/skills/skills.service.ts`
- [Personal journey](https://github.com/popxicallab/pop-os/blob/main/src/me/me.service.ts): `src/me/me.service.ts`
- [Self assessment](https://github.com/popxicallab/pop-os/blob/main/src/self-assess/self-assess.service.ts): `src/self-assess/self-assess.service.ts`

### Finance and Insights

- [Autocount accounting](https://github.com/popxicallab/pop-os/blob/main/src/autocount/autocount.service.ts): `src/autocount/autocount.service.ts`
- [Operations dashboard](https://github.com/popxicallab/pop-os/blob/main/src/dashboard/dashboard.service.ts): `src/dashboard/dashboard.service.ts`
- [Financial overview](https://github.com/popxicallab/pop-os/blob/main/src/financial/financial.service.ts): `src/financial/financial.service.ts`
- [Sales commissions](https://github.com/popxicallab/pop-os/blob/main/src/sales-performance/sales-performance.service.ts): `src/sales-performance/sales-performance.service.ts`
- [Audit log](https://github.com/popxicallab/pop-os/blob/main/src/audit/audit.service.ts): `src/audit/audit.service.ts`

### Identity and Notifications

- [Login and access](https://github.com/popxicallab/pop-os/blob/main/src/auth/auth.service.ts): `src/auth/auth.service.ts`
- [Notification rules](https://github.com/popxicallab/pop-os/blob/main/src/mattermost/notification-rules.service.ts): `src/mattermost/notification-rules.service.ts`
- [Mattermost messaging](https://github.com/popxicallab/pop-os/blob/main/src/mattermost/mattermost.service.ts): `src/mattermost/mattermost.service.ts`
- [Email notifications](https://github.com/popxicallab/pop-os/blob/main/src/notifications/notifications.service.ts): `src/notifications/notifications.service.ts`
- [Role and money guards](https://github.com/popxicallab/pop-os/blob/main/src/common/roles.ts): `src/common/roles.ts`
- [PostgreSQL via Prisma](https://github.com/popxicallab/pop-os/blob/main/src/prisma.service.ts): `src/prisma.service.ts`

### Other components

- **Studio user**

## Connections

- Studio user → Login and access: signs in
- Studio user → Sales pipeline: manages pipeline
- Sales pipeline → Project management: converts won lead
- Sales pipeline → Won deals and jobs: tracks won deal
- Sales pipeline → Autocount accounting: creates quotation
- Project management → Autocount accounting: creates invoice
- Won deals and jobs → Job attachments: tracks files
- Won deals and jobs → Autocount accounting: links documents
- Project management → Production lanes: routes by lane
- Project management → Capacity planning: allocates weekly capacity
- Capacity planning → Capacity data contract: uses contract (evidence: `src/capacity/capacity.controller.ts`)
- Project management → Staffing recommendations: requests suggestions
- Project management → PPM rules: uses quadrant rules
- Studio user → Accounts and contacts: manages clients
- Studio user → People records: maintains staff records
- People records → Skills and ratings: records skills
- People records → Personal journey: views personal history
- Studio user → Self assessment: submits assessment
- Studio user → Operations dashboard: views command centre
- Studio user → Financial overview: reviews finances
- Studio user → Sales commissions: tracks commissions
- Sales pipeline → Audit log: logs changes (evidence: `src/leads/leads.controller.ts`)
- Project management → Audit log: logs changes (evidence: `src/projects/projects.controller.ts`)
- Studio user → Notification rules: configures messages
- Notification rules → Mattermost messaging: dispatches messages (evidence: `src/mattermost/notification-rules.service.ts`)
- Login and access → Email notifications: sends reset link (evidence: `src/auth/auth.service.ts`)
- Login and access → PostgreSQL via Prisma: reads and updates users (evidence: `src/auth/auth.service.ts`)
- Audit log → PostgreSQL via Prisma: writes and queries logs (evidence: `src/audit/audit.service.ts`)
- Capacity planning → PostgreSQL via Prisma: reads and writes allocations (evidence: `src/capacity/capacity.service.ts`)
- People records → Audit log: records changes (evidence: `src/people/people.controller.ts`)
- Sales pipeline → Role and money guards: enforces job access (evidence: `src/leads/leads.controller.ts`)
