# sidsahoo1203/companyos architecture

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

- Interactive diagram: https://gitdiagram.com/sidsahoo1203/companyos
- Repository: https://github.com/sidsahoo1203/companyos

## Overview

CompanyOS is a multi-tenant operations workspace for digital agencies. Its main user flow is to create or join a workspace, build a permission-aware knowledge library, then use versioned procedures and pinned skills to create auditable draft runs for human review; proposed actions enter an approval inbox and are recorded only in a local outbox. The graph preserves membership/invitation, document processing, assistant search, automation, and approval capabilities. Some route and UI implementations were not sampled, so links involving them are omitted unless documented or evidenced by the source index.

Main entry points: [`src/lib/knowledge.ts`](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/knowledge.ts) (Knowledge service), [`src/lib/agents.ts`](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agents.ts) (Procedure and run service), [`src/lib/db.ts`](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/db.ts) (Tenant database access), [`src/lib/http.ts`](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/http.ts) (API session and safeguards)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Identity and workspaces"]
  node_auth_api["Authentication API<br/>[route.ts]"]
  node_auth["Auth and sessions<br/>[auth.ts]"]
  node_workspace_api["Workspace APIs<br/>[route.ts]"]
  node_workspace_service["Workspace membership<br/>[workspaces.ts]"]
end

subgraph group_knowledge["Knowledge library"]
  node_knowledge_api["Knowledge APIs<br/>[route.ts]"]
  node_assistant_api["Assistant API<br/>[route.ts]"]
  node_knowledge_service["Knowledge service<br/>[knowledge.ts]"]
  node_document_processing["Document processing"]
  node_knowledge_validation["Knowledge validation"]
end

subgraph group_automation["Procedures and runs"]
  node_procedures_api["Procedure APIs<br/>[route.ts]"]
  node_runs_api["Run APIs<br/>[route.ts]"]
  node_agent_service["Procedure and run service<br/>[agents.ts]"]
  node_agent_engine["Draft engine<br/>[agent-engine.ts]"]
  node_agent_contracts["Automation contracts<br/>[agent-contracts.ts]"]
end

subgraph group_approvals["Review and approvals"]
  node_approvals_api["Approval APIs<br/>[route.ts]"]
  node_approval_service["Approval service<br/>[approvals.ts]"]
end

subgraph group_platform["Shared runtime"]
  node_db["Tenant database access<br/>[db.ts]"]
  node_http["API session and safeguards<br/>[http.ts]"]
  node_validation["Request validation<br/>[validation.ts]"]
end

node_user(("Agency user"))
node_postgres[("PostgreSQL")]

node_user -->|"signs in"| node_auth_api
node_auth_api -->|"dispatches to"| node_auth
node_user -->|"manages workspace"| node_workspace_api
node_workspace_api -->|"calls"| node_workspace_service
node_user -->|"manages sources"| node_knowledge_api
node_knowledge_api -->|"calls"| node_knowledge_service
node_user -->|"searches knowledge"| node_assistant_api
node_assistant_api -->|"calls"| node_knowledge_service
node_knowledge_service -->|"validates uploads"| node_knowledge_validation
node_knowledge_service -->|"processes bytes"| node_document_processing
node_user -->|"defines procedures"| node_procedures_api
node_procedures_api -->|"calls"| node_agent_service
node_user -->|"starts draft run"| node_runs_api
node_runs_api -->|"calls"| node_agent_service
node_agent_service -->|"generates draft"| node_agent_engine
node_agent_engine -->|"validates output"| node_agent_contracts
node_agent_service -->|"uses schemas"| node_agent_contracts
node_user -->|"reviews drafts"| node_approvals_api
node_approvals_api -->|"calls"| node_approval_service
node_workspace_service -->|"runs as actor"| node_db
node_knowledge_service -->|"runs as actor"| node_db
node_agent_service -->|"runs as actor"| node_db
node_approval_service -->|"runs as actor"| node_db
node_db -->|"connects to"| node_postgres
node_workspace_api -->|"uses API wrapper"| node_http
node_workspace_api -->|"parses input"| node_validation
node_knowledge_api -->|"uses API wrapper"| node_http
node_knowledge_api -->|"parses input"| node_knowledge_validation
node_procedures_api -->|"uses API wrapper"| node_http
node_procedures_api -->|"parses input"| node_agent_contracts
node_runs_api -->|"uses API wrapper"| node_http
node_approvals_api -->|"uses API wrapper"| node_http
node_approvals_api -->|"parses input"| node_validation

click node_auth_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/auth/%5B...all%5D/route.ts"
click node_auth "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/auth.ts"
click node_workspace_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/route.ts"
click node_workspace_service "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/workspaces.ts"
click node_knowledge_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/knowledge/route.ts"
click node_assistant_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/assistant/route.ts"
click node_knowledge_service "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/knowledge.ts"
click node_document_processing "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/document-processing.ts"
click node_knowledge_validation "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/knowledge-validation.ts"
click node_procedures_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/procedures/route.ts"
click node_runs_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/runs/route.ts"
click node_agent_service "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agents.ts"
click node_agent_engine "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agent-engine.ts"
click node_agent_contracts "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agent-contracts.ts"
click node_approvals_api "https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/approvals/route.ts"
click node_approval_service "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/approvals.ts"
click node_db "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/db.ts"
click node_http "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/http.ts"
click node_validation "https://github.com/sidsahoo1203/companyos/blob/main/src/lib/validation.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_auth_api,node_auth,node_workspace_api,node_workspace_service,node_user toneBlue
class node_knowledge_api,node_assistant_api,node_knowledge_service,node_document_processing,node_knowledge_validation,node_postgres toneAmber
class node_procedures_api,node_runs_api,node_agent_service,node_agent_engine,node_agent_contracts toneMint
class node_approvals_api,node_approval_service toneRose
class node_db,node_http,node_validation toneIndigo
```

## Components

### Identity and workspaces

- [Authentication API](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/auth/%5B...all%5D/route.ts): `src/app/api/auth/[...all]/route.ts`
- [Auth and sessions](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/auth.ts): `src/lib/auth.ts`
- [Workspace APIs](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/route.ts): `src/app/api/workspaces/route.ts`
- [Workspace membership](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/workspaces.ts): `src/lib/workspaces.ts`

### Knowledge library

- [Knowledge APIs](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/knowledge/route.ts): `src/app/api/workspaces/[workspaceId]/knowledge/route.ts`
- [Assistant API](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/assistant/route.ts): `src/app/api/workspaces/[workspaceId]/assistant/route.ts`
- [Knowledge service](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/knowledge.ts): `src/lib/knowledge.ts`
- [Document processing](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/document-processing.ts): `src/lib/document-processing.ts`
- [Knowledge validation](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/knowledge-validation.ts): `src/lib/knowledge-validation.ts`

### Procedures and runs

- [Procedure APIs](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/procedures/route.ts): `src/app/api/workspaces/[workspaceId]/procedures/route.ts`
- [Run APIs](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/runs/route.ts): `src/app/api/workspaces/[workspaceId]/runs/route.ts`
- [Procedure and run service](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agents.ts): `src/lib/agents.ts`
- [Draft engine](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agent-engine.ts): `src/lib/agent-engine.ts`
- [Automation contracts](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/agent-contracts.ts): `src/lib/agent-contracts.ts`

### Review and approvals

- [Approval APIs](https://github.com/sidsahoo1203/companyos/blob/main/src/app/api/workspaces/%5BworkspaceId%5D/approvals/route.ts): `src/app/api/workspaces/[workspaceId]/approvals/route.ts`
- [Approval service](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/approvals.ts): `src/lib/approvals.ts`

### Shared runtime

- [Tenant database access](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/db.ts): `src/lib/db.ts`
- [API session and safeguards](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/http.ts): `src/lib/http.ts`
- [Request validation](https://github.com/sidsahoo1203/companyos/blob/main/src/lib/validation.ts): `src/lib/validation.ts`

### Other components

- **Agency user**
- **PostgreSQL**

## Connections

- Agency user → Authentication API: signs in (evidence: `src/app/api/auth/[...all]/route.ts`)
- Authentication API → Auth and sessions: dispatches to (evidence: `src/app/api/auth/[...all]/route.ts`)
- Agency user → Workspace APIs: manages workspace (evidence: `README.md`)
- Workspace APIs → Workspace membership: calls (evidence: `src/app/api/workspaces/route.ts`)
- Agency user → Knowledge APIs: manages sources (evidence: `README.md`)
- Knowledge APIs → Knowledge service: calls (evidence: `src/app/api/workspaces/[workspaceId]/knowledge/route.ts`)
- Agency user → Assistant API: searches knowledge (evidence: `README.md`)
- Assistant API → Knowledge service: calls (evidence: `src/app/api/workspaces/[workspaceId]/assistant/route.ts`)
- Knowledge service → Knowledge validation: validates uploads (evidence: `src/lib/knowledge.ts`)
- Knowledge service → Document processing: processes bytes (evidence: `src/lib/knowledge.ts`)
- Agency user → Procedure APIs: defines procedures (evidence: `README.md`)
- Procedure APIs → Procedure and run service: calls (evidence: `src/app/api/workspaces/[workspaceId]/procedures/route.ts`)
- Agency user → Run APIs: starts draft run (evidence: `README.md`)
- Run APIs → Procedure and run service: calls (evidence: `src/app/api/workspaces/[workspaceId]/runs/route.ts`)
- Procedure and run service → Draft engine: generates draft (evidence: `src/lib/agents.ts`)
- Draft engine → Automation contracts: validates output (evidence: `src/lib/agent-engine.ts`)
- Procedure and run service → Automation contracts: uses schemas (evidence: `src/lib/agents.ts`)
- Agency user → Approval APIs: reviews drafts (evidence: `README.md`)
- Approval APIs → Approval service: calls (evidence: `src/app/api/workspaces/[workspaceId]/approvals/route.ts`)
- Workspace membership → Tenant database access: runs as actor (evidence: `src/lib/workspaces.ts`)
- Knowledge service → Tenant database access: runs as actor (evidence: `src/lib/knowledge.ts`)
- Procedure and run service → Tenant database access: runs as actor (evidence: `src/lib/agents.ts`)
- Approval service → Tenant database access: runs as actor (evidence: `src/lib/approvals.ts`)
- Tenant database access → PostgreSQL: connects to (evidence: `src/lib/db.ts`)
- Workspace APIs → API session and safeguards: uses API wrapper (evidence: `src/app/api/workspaces/route.ts`)
- Workspace APIs → Request validation: parses input (evidence: `src/app/api/workspaces/route.ts`)
- Knowledge APIs → API session and safeguards: uses API wrapper (evidence: `src/app/api/workspaces/[workspaceId]/knowledge/route.ts`)
- Knowledge APIs → Knowledge validation: parses input (evidence: `src/app/api/workspaces/[workspaceId]/knowledge/route.ts`)
- Procedure APIs → API session and safeguards: uses API wrapper (evidence: `src/app/api/workspaces/[workspaceId]/procedures/route.ts`)
- Procedure APIs → Automation contracts: parses input (evidence: `src/app/api/workspaces/[workspaceId]/procedures/route.ts`)
- Run APIs → API session and safeguards: uses API wrapper (evidence: `src/app/api/workspaces/[workspaceId]/runs/route.ts`)
- Approval APIs → API session and safeguards: uses API wrapper (evidence: `src/app/api/workspaces/[workspaceId]/approvals/route.ts`)
- Approval APIs → Request validation: parses input (evidence: `src/app/api/workspaces/[workspaceId]/approvals/route.ts`)
