# cloudandbeyond2/colossusiq-new architecture

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

- Interactive diagram: https://gitdiagram.com/cloudandbeyond2/colossusiq-new
- Repository: https://github.com/cloudandbeyond2/colossusiq-new

## Overview

CollossusIQ is a multi-role, multi-college education platform: visitors can explore colleges and apply, while authenticated users access role-specific academic, learning, teaching, career, administration, and certificate features. The evident runtime path includes browser API requests handled by a catch-all API route, with session and tenant checks around portal access. The graph preserves major feature areas visible in the tree, but many UI-to-service and persistence relationships are unverified because their source was not sampled.

Main entry points: [`frontend/src/app/[role]/[module]/page.tsx`](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/%5Brole%5D/%5Bmodule%5D/page.tsx) (Role portal), [`frontend/src/app/api/v1/[...path]/route.ts`](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/api/v1/%5B...path%5D/route.ts) (API handler), [`frontend/src/lib/auth/session.ts`](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/session.ts) (Signed sessions), [`frontend/src/app/(marketing)/page.tsx`](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/(marketing)/page.tsx) (Marketing site)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Public entry"]
  node_marketing["Marketing site<br/>[page.tsx]"]
  node_college_site["College sites<br/>[page.tsx]"]
  node_admissions["Admissions<br/>[route.ts]"]
end

subgraph group_identity["Identity and tenancy"]
  node_login["Login and MFA<br/>[page.tsx]"]
  node_roles["Role permissions<br/>[roles.ts]"]
  node_session["Signed sessions<br/>[session.ts]"]
  node_totp["Authenticator MFA<br/>[totp.ts]"]
end

subgraph group_platform["Portal capabilities"]
  node_portal["Role portal<br/>[page.tsx]"]
  node_learning["Learning and exams<br/>[lesson-content.tsx]"]
  node_teaching["Teaching studio"]
  node_admin["Institution operations"]
  node_careers["Career and placement"]
  node_certificates["Certificates"]
  node_evaluation["Evaluation review"]
end

subgraph group_runtime["API and data"]
  node_api_client["API client<br/>[client.ts]"]
  node_api["API handler<br/>[route.ts]"]
  node_data_context["Request data context<br/>[index.ts]"]
  node_postgres[("PostgreSQL data")]
  node_certificate_signing["Certificate signing"]
end

node_visitor(("Visitor"))

node_visitor -->|"browses"| node_marketing
node_marketing -.->|"finds colleges"| node_college_site
node_visitor -.->|"signs in"| node_login
node_login -.->|"authenticates"| node_api
node_api -->|"issues session"| node_session
node_api -->|"sets request context"| node_data_context
node_data_context -.->|"selects backend"| node_postgres
node_session -->|"validates role"| node_roles
node_portal -.->|"uses role model"| node_roles
node_portal -.->|"offers learning"| node_learning
node_portal -.->|"offers teaching"| node_teaching
node_portal -.->|"offers operations"| node_admin
node_portal -.->|"offers career tools"| node_careers
node_portal -.->|"offers certificates"| node_certificates
node_evaluation -->|"sends mutations"| node_api_client
node_api_client -->|"fetches API"| node_api
node_api -.->|"signs certificates"| node_certificate_signing
node_api -->|"handles applications"| node_admissions
node_totp -.->|"MFA workflow"| node_session

click node_marketing "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/(marketing)/page.tsx"
click node_college_site "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/(college-site)/colleges/%5Bid%5D/page.tsx"
click node_admissions "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/api/v1/%5B...path%5D/route.ts"
click node_login "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/login/page.tsx"
click node_roles "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/roles.ts"
click node_session "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/session.ts"
click node_totp "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/totp.ts"
click node_portal "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/%5Brole%5D/%5Bmodule%5D/page.tsx"
click node_learning "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/learning/lesson-content.tsx"
click node_teaching "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/teaching/teaching-studio.tsx"
click node_admin "https://github.com/cloudandbeyond2/colossusiq-new/tree/main/frontend/src/components/portal/bespoke"
click node_careers "https://github.com/cloudandbeyond2/colossusiq-new/tree/main/frontend/src/components/portal/bespoke"
click node_certificates "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/certificate/certificate-sheet.tsx"
click node_evaluation "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/portal/bespoke/evaluation-review.tsx"
click node_api_client "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/api/client.ts"
click node_api "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/api/v1/%5B...path%5D/route.ts"
click node_data_context "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/data/index.ts"
click node_postgres "https://github.com/cloudandbeyond2/colossusiq-new/tree/main/frontend/src/lib/data/postgres"
click node_certificate_signing "https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/security/certificate-signature.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_marketing,node_college_site,node_admissions toneBlue
class node_login,node_roles,node_session,node_totp toneAmber
class node_portal,node_learning,node_teaching,node_admin,node_careers,node_certificates,node_evaluation toneMint
class node_api_client,node_api,node_data_context,node_postgres,node_certificate_signing toneRose
class node_visitor toneIndigo
```

## Components

### Public entry

- [Marketing site](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/(marketing)/page.tsx): `frontend/src/app/(marketing)/page.tsx`
- [College sites](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/(college-site)/colleges/%5Bid%5D/page.tsx): `frontend/src/app/(college-site)/colleges/[id]/page.tsx`
- [Admissions](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/api/v1/%5B...path%5D/route.ts): `frontend/src/app/api/v1/[...path]/route.ts`

### Identity and tenancy

- [Login and MFA](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/login/page.tsx): `frontend/src/app/login/page.tsx`
- [Role permissions](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/roles.ts): `frontend/src/lib/auth/roles.ts`
- [Signed sessions](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/session.ts): `frontend/src/lib/auth/session.ts`
- [Authenticator MFA](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/auth/totp.ts): `frontend/src/lib/auth/totp.ts`

### Portal capabilities

- [Role portal](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/%5Brole%5D/%5Bmodule%5D/page.tsx): `frontend/src/app/[role]/[module]/page.tsx`
- [Learning and exams](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/learning/lesson-content.tsx): `frontend/src/components/learning/lesson-content.tsx`
- [Teaching studio](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/teaching/teaching-studio.tsx): `frontend/src/components/teaching/teaching-studio.tsx`
- [Institution operations](https://github.com/cloudandbeyond2/colossusiq-new/tree/main/frontend/src/components/portal/bespoke): `frontend/src/components/portal/bespoke`
- [Career and placement](https://github.com/cloudandbeyond2/colossusiq-new/tree/main/frontend/src/components/portal/bespoke): `frontend/src/components/portal/bespoke`
- [Certificates](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/certificate/certificate-sheet.tsx): `frontend/src/components/certificate/certificate-sheet.tsx`
- [Evaluation review](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/components/portal/bespoke/evaluation-review.tsx): `frontend/src/components/portal/bespoke/evaluation-review.tsx`

### API and data

- [API client](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/api/client.ts): `frontend/src/lib/api/client.ts`
- [API handler](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/app/api/v1/%5B...path%5D/route.ts): `frontend/src/app/api/v1/[...path]/route.ts`
- [Request data context](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/data/index.ts): `frontend/src/lib/data/index.ts`
- [PostgreSQL data](https://github.com/cloudandbeyond2/colossusiq-new/tree/main/frontend/src/lib/data/postgres): `frontend/src/lib/data/postgres`
- [Certificate signing](https://github.com/cloudandbeyond2/colossusiq-new/blob/main/frontend/src/lib/security/certificate-signature.ts): `frontend/src/lib/security/certificate-signature.ts`

### Other components

- **Visitor**

## Connections

- Visitor → Marketing site: browses (evidence: `frontend/src/app/(marketing)/page.tsx`)
- Marketing site → College sites: finds colleges
- Visitor → Login and MFA: signs in
- Login and MFA → API handler: authenticates
- API handler → Signed sessions: issues session (evidence: `frontend/src/app/api/v1/[...path]/route.ts`)
- API handler → Request data context: sets request context (evidence: `frontend/src/app/api/v1/[...path]/route.ts`)
- Request data context → PostgreSQL data: selects backend
- Signed sessions → Role permissions: validates role (evidence: `frontend/src/lib/auth/session.ts`)
- Role portal → Role permissions: uses role model
- Role portal → Learning and exams: offers learning
- Role portal → Teaching studio: offers teaching
- Role portal → Institution operations: offers operations
- Role portal → Career and placement: offers career tools
- Role portal → Certificates: offers certificates
- Evaluation review → API client: sends mutations (evidence: `frontend/src/components/portal/bespoke/evaluation-review.tsx`)
- API client → API handler: fetches API (evidence: `frontend/src/lib/api/client.ts`)
- API handler → Certificate signing: signs certificates
- API handler → Admissions: handles applications (evidence: `frontend/src/app/api/v1/[...path]/route.ts`)
- Authenticator MFA → Signed sessions: MFA workflow
