# kachechki/chanceofidea-backend architecture

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

- Interactive diagram: https://gitdiagram.com/kachechki/chanceofidea-backend
- Repository: https://github.com/kachechki/chanceofidea-backend

## Overview

Chance of Idea is a NestJS REST backend for a marketplace of unfinished projects. The main workflow is GitHub-based sign-in, project publishing and discovery, applications to take over a project, then confirmations that coordinate repository transfer. Categories and tags organize listings; user, project, application, and transfer state persist in PostgreSQL. The graph follows documented capabilities and sampled controller/service calls; links for unsampled routes are limited to README evidence, and no unsampled implementation details are assumed.

Main entry points: [`src/database/data-source.ts`](https://github.com/kachechki/chanceofidea-backend/blob/main/src/database/data-source.ts) (PostgreSQL), [`src/project/services/Project.service.ts`](https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/services/Project.service.ts) (Project lifecycle & search), [`src/transfer-session/services/TransferSession.service.ts`](https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/services/TransferSession.service.ts) (Transfer sessions), [`src/application/services/Application.service.ts`](https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/services/Application.service.ts) (Applications & decisions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_identity["Identity & GitHub"]
  node_auth["OAuth &amp; JWT<br/>[Auth.service.ts]"]
  node_auth_guard["JWT guard<br/>[Auth.guard.ts]"]
  node_github_access["GitHub credentials"]
  node_users["User profiles<br/>[User.service.ts]"]
  node_github_api["GitHub API<br/>[Github.service.ts]"]
  node_github_routes["Repository lookup"]
end

subgraph group_market["Project Marketplace"]
  node_projects_api["Project routes"]
  node_projects["Project lifecycle &amp; search<br/>[Project.service.ts]"]
  node_project_guard["Owner permissions<br/>[Project.guard.ts]"]
end

subgraph group_takeover["Takeover Workflow"]
  node_applications_api["Application routes"]
  node_applications["Applications &amp; decisions"]
  node_transfer_api["Transfer confirmations"]
  node_transfers["Transfer sessions"]
end

subgraph group_catalog["Listing Organization"]
  node_categories["Categories<br/>[Category.sevice.ts]"]
  node_tags["Tags<br/>[Tag.service.ts]"]
end

subgraph group_persistence["Persistence"]
  node_postgres[("PostgreSQL<br/>[data-source.ts]")]
  node_project_entity["Project records<br/>[Project.entity.ts]"]
  node_user_entity["User records<br/>[User.entity.ts]"]
  node_application_entity["Application records"]
  node_github_entity["GitHub token records"]
  node_transfer_entity["Transfer records"]
  node_category_entity["Category records<br/>[Category.entity.ts]"]
  node_tag_entity["Tag records<br/>[Tag.entity.ts]"]
end

node_visitor(("API client"))

node_visitor -->|"starts OAuth"| node_auth
node_visitor -->|"uses listings"| node_projects_api
node_visitor -->|"submits applications"| node_applications_api
node_visitor -->|"confirms transfer"| node_transfer_api
node_auth -->|"saves identity"| node_users
node_auth -->|"stores credentials"| node_github_access
node_auth_guard -->|"authenticates requests"| node_visitor
node_auth_guard -->|"refreshes tokens"| node_auth
node_github_access -->|"persists tokens"| node_github_entity
node_users -->|"reads and writes"| node_user_entity
node_github_routes -->|"requests repositories"| node_github_api
node_github_api -->|"loads credentials"| node_github_access
node_github_api -->|"checks transfer state"| node_transfers
node_projects_api -->|"guards routes"| node_auth_guard
node_projects_api -->|"checks ownership"| node_project_guard
node_project_guard -->|"loads project"| node_projects
node_projects_api -->|"manages listings"| node_projects
node_projects -->|"reads and writes"| node_project_entity
node_projects -->|"loads owners"| node_users
node_projects -->|"resolves categories"| node_categories
node_projects -->|"resolves tags"| node_tags
node_applications_api -->|"guards routes"| node_auth_guard
node_applications_api -->|"submits decisions"| node_applications
node_applications -->|"reads and writes"| node_application_entity
node_applications -->|"starts transfer"| node_projects
node_applications -.->|"creates session"| node_transfers
node_transfer_api -->|"guards routes"| node_auth_guard
node_transfer_api -->|"records confirmations"| node_transfers
node_transfers -->|"reads and writes"| node_transfer_entity
node_transfers -->|"validates repository"| node_github_api
node_transfers -->|"loads application"| node_applications
node_categories -->|"reads and writes"| node_category_entity
node_tags -->|"reads and writes"| node_tag_entity
node_postgres -->|"stores"| node_project_entity
node_postgres -->|"stores"| node_user_entity
node_postgres -->|"stores"| node_application_entity
node_postgres -->|"stores"| node_github_entity
node_postgres -->|"stores"| node_transfer_entity
node_postgres -->|"stores"| node_category_entity
node_postgres -->|"stores"| node_tag_entity

click node_auth "https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/services/Auth.service.ts"
click node_auth_guard "https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/guards/Auth.guard.ts"
click node_github_access "https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/services/GithubAccess.service.ts"
click node_users "https://github.com/kachechki/chanceofidea-backend/blob/main/src/user/services/User.service.ts"
click node_github_api "https://github.com/kachechki/chanceofidea-backend/blob/main/src/github/services/Github.service.ts"
click node_github_routes "https://github.com/kachechki/chanceofidea-backend/blob/main/src/github/github.controller.ts"
click node_projects_api "https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/project.controller.ts"
click node_projects "https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/services/Project.service.ts"
click node_project_guard "https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/guards/Project.guard.ts"
click node_applications_api "https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/application.controller.ts"
click node_applications "https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/services/Application.service.ts"
click node_transfer_api "https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/transfer-session.controller.ts"
click node_transfers "https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/services/TransferSession.service.ts"
click node_categories "https://github.com/kachechki/chanceofidea-backend/blob/main/src/category/services/Category.sevice.ts"
click node_tags "https://github.com/kachechki/chanceofidea-backend/blob/main/src/tag/services/Tag.service.ts"
click node_postgres "https://github.com/kachechki/chanceofidea-backend/blob/main/src/database/data-source.ts"
click node_project_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/entities/Project.entity.ts"
click node_user_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/user/entities/User.entity.ts"
click node_application_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/entities/Application.entity.ts"
click node_github_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/entities/GithubAccess.entity.ts"
click node_transfer_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/entities/TransferSession.entity.ts"
click node_category_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/category/entities/Category.entity.ts"
click node_tag_entity "https://github.com/kachechki/chanceofidea-backend/blob/main/src/tag/entities/Tag.entity.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,node_auth_guard,node_github_access,node_users,node_github_api,node_github_routes,node_visitor toneBlue
class node_projects_api,node_projects,node_project_guard toneAmber
class node_applications_api,node_applications,node_transfer_api,node_transfers toneMint
class node_categories,node_tags toneRose
class node_postgres,node_project_entity,node_user_entity,node_application_entity,node_github_entity,node_transfer_entity,node_category_entity,node_tag_entity toneIndigo
```

## Components

### Identity & GitHub

- [OAuth & JWT](https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/services/Auth.service.ts): `src/auth/services/Auth.service.ts`
- [JWT guard](https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/guards/Auth.guard.ts): `src/auth/guards/Auth.guard.ts`
- [GitHub credentials](https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/services/GithubAccess.service.ts): `src/auth/services/GithubAccess.service.ts`
- [User profiles](https://github.com/kachechki/chanceofidea-backend/blob/main/src/user/services/User.service.ts): `src/user/services/User.service.ts`
- [GitHub API](https://github.com/kachechki/chanceofidea-backend/blob/main/src/github/services/Github.service.ts): `src/github/services/Github.service.ts`
- [Repository lookup](https://github.com/kachechki/chanceofidea-backend/blob/main/src/github/github.controller.ts): `src/github/github.controller.ts`

### Project Marketplace

- [Project routes](https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/project.controller.ts): `src/project/project.controller.ts`
- [Project lifecycle & search](https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/services/Project.service.ts): `src/project/services/Project.service.ts`
- [Owner permissions](https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/guards/Project.guard.ts): `src/project/guards/Project.guard.ts`

### Takeover Workflow

- [Application routes](https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/application.controller.ts): `src/application/application.controller.ts`
- [Applications & decisions](https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/services/Application.service.ts): `src/application/services/Application.service.ts`
- [Transfer confirmations](https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/transfer-session.controller.ts): `src/transfer-session/transfer-session.controller.ts`
- [Transfer sessions](https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/services/TransferSession.service.ts): `src/transfer-session/services/TransferSession.service.ts`

### Listing Organization

- [Categories](https://github.com/kachechki/chanceofidea-backend/blob/main/src/category/services/Category.sevice.ts): `src/category/services/Category.sevice.ts`
- [Tags](https://github.com/kachechki/chanceofidea-backend/blob/main/src/tag/services/Tag.service.ts): `src/tag/services/Tag.service.ts`

### Persistence

- [PostgreSQL](https://github.com/kachechki/chanceofidea-backend/blob/main/src/database/data-source.ts): `src/database/data-source.ts`
- [Project records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/project/entities/Project.entity.ts): `src/project/entities/Project.entity.ts`
- [User records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/user/entities/User.entity.ts): `src/user/entities/User.entity.ts`
- [Application records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/application/entities/Application.entity.ts): `src/application/entities/Application.entity.ts`
- [GitHub token records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/auth/entities/GithubAccess.entity.ts): `src/auth/entities/GithubAccess.entity.ts`
- [Transfer records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/transfer-session/entities/TransferSession.entity.ts): `src/transfer-session/entities/TransferSession.entity.ts`
- [Category records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/category/entities/Category.entity.ts): `src/category/entities/Category.entity.ts`
- [Tag records](https://github.com/kachechki/chanceofidea-backend/blob/main/src/tag/entities/Tag.entity.ts): `src/tag/entities/Tag.entity.ts`

### Other components

- **API client**

## Connections

- API client → OAuth & JWT: starts OAuth (evidence: `README.md`)
- API client → Project routes: uses listings (evidence: `README.md`)
- API client → Application routes: submits applications (evidence: `README.md`)
- API client → Transfer confirmations: confirms transfer (evidence: `README.md`)
- OAuth & JWT → User profiles: saves identity (evidence: `src/auth/services/Auth.service.ts`)
- OAuth & JWT → GitHub credentials: stores credentials (evidence: `src/auth/services/Auth.service.ts`)
- JWT guard → API client: authenticates requests (evidence: `src/auth/guards/Auth.guard.ts`)
- JWT guard → OAuth & JWT: refreshes tokens (evidence: `src/auth/guards/Auth.guard.ts`)
- GitHub credentials → GitHub token records: persists tokens (evidence: `src/auth/services/GithubAccess.service.ts`)
- User profiles → User records: reads and writes (evidence: `src/user/services/User.service.ts`)
- Repository lookup → GitHub API: requests repositories (evidence: `src/github/github.controller.ts`)
- GitHub API → GitHub credentials: loads credentials (evidence: `src/github/services/Github.service.ts`)
- GitHub API → Transfer sessions: checks transfer state (evidence: `src/github/services/Github.service.ts`)
- Project routes → JWT guard: guards routes (evidence: `src/project/project.controller.ts`)
- Project routes → Owner permissions: checks ownership (evidence: `src/project/project.controller.ts`)
- Owner permissions → Project lifecycle & search: loads project (evidence: `src/project/guards/Project.guard.ts`)
- Project routes → Project lifecycle & search: manages listings (evidence: `src/project/project.controller.ts`)
- Project lifecycle & search → Project records: reads and writes (evidence: `src/project/services/Project.service.ts`)
- Project lifecycle & search → User profiles: loads owners (evidence: `src/project/services/Project.service.ts`)
- Project lifecycle & search → Categories: resolves categories (evidence: `src/project/services/Project.service.ts`)
- Project lifecycle & search → Tags: resolves tags (evidence: `src/project/services/Project.service.ts`)
- Application routes → JWT guard: guards routes (evidence: `src/application/application.controller.ts`)
- Application routes → Applications & decisions: submits decisions (evidence: `src/application/application.controller.ts`)
- Applications & decisions → Application records: reads and writes (evidence: `src/application/services/Application.service.ts`)
- Applications & decisions → Project lifecycle & search: starts transfer (evidence: `src/application/services/Application.service.ts`)
- Applications & decisions → Transfer sessions: creates session (evidence: `src/transfer-session/services/TransferSession.service.ts`)
- Transfer confirmations → JWT guard: guards routes (evidence: `README.md`)
- Transfer confirmations → Transfer sessions: records confirmations (evidence: `README.md`)
- Transfer sessions → Transfer records: reads and writes (evidence: `src/transfer-session/services/TransferSession.service.ts`)
- Transfer sessions → GitHub API: validates repository (evidence: `src/transfer-session/services/TransferSession.service.ts`)
- Transfer sessions → Applications & decisions: loads application (evidence: `src/transfer-session/services/TransferSession.service.ts`)
- Categories → Category records: reads and writes (evidence: `src/category/services/Category.sevice.ts`)
- Tags → Tag records: reads and writes (evidence: `src/tag/services/Tag.service.ts`)
- PostgreSQL → Project records: stores
- PostgreSQL → User records: stores
- PostgreSQL → Application records: stores
- PostgreSQL → GitHub token records: stores
- PostgreSQL → Transfer records: stores
- PostgreSQL → Category records: stores
- PostgreSQL → Tag records: stores