Skip to content

docs: rewrite README to reflect the actual API #66

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
D4M13N-D3V merged 1 commit into from
Jun 1, 2026
Merged

docs: rewrite README to reflect the actual API #66

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 129 additions & 54 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,94 +1,169 @@
# Comissions.app
# comissions.app — Core API

## Description
The backend REST API for **comissions.app**, a platform where artists offer
commission services and customers request, pay for, and review them
(Skeb-style). This service owns users, artist profiles, commission requests,
payments, and the public discovery surface.

This is a application that provides a platform to allow creatives to sell their services without intense moderation.
> Part of a multi-repo project: this Core API, a separate web UI
> (`comissions-app-ui`), and deployment manifests (`comissions-app-argocd`).

## Table of Contents
## Tech stack

- [Project Name](#project-name)
- [Description](#description)
- [Table of Contents](#table-of-contents)
- [Prerequisites](#prerequisites)
- [Getting Started](#getting-started)
- [Clone the Repository](#clone-the-repository)
- [Build and Run with Docker](#build-and-run-with-docker)
- [Usage](#usage)
- [Swagger UI](#swagger-ui)
- [Contributing](#contributing)
- [License](#license)
- **.NET 8** / ASP.NET Core Web API
- **PostgreSQL** via **Entity Framework Core 8** (Npgsql)
- **Auth0** for authentication (JWT bearer) and scope-based authorization
- **Stripe Connect** for marketplace payments and artist payouts
- **Novu** for transactional notifications
- **Swagger / OpenAPI** for API docs and SDK generation
- Local file storage by default; an imgcdn provider is available behind the
`IStorageService` abstraction

## Prerequisites
## Repository layout

- [.NET 8 SDK](https://dotnet.microsoft.com/download)
- [Docker](https://www.docker.com/get-started)
```
src/
├── comissions.app.api/ # the Web API (controllers, entities, services, EF migrations)
├── comissions.app.database/ # shared database project
├── comissions.app.database.migrator/# standalone migration runner (for CI/CD / init jobs)
└── comissions.app.sdk/ # generated C# client SDK (from the OpenAPI spec)
```

## Getting Started
### API surface (high level)

### Clone the Repository
| Area | Routes | Notes |
| --- | --- | --- |
| Discovery | `GET /api/Discovery/Artists…` | Public: browse artists, portfolios, reviews |
| User | `/api/User` | Read/update the authenticated user |
| Artist | `/api/Artist…` | Profile, page settings, portfolio, payments, reviews |
| Artist access | `/api/ArtistAccessRequest` | Request to become a seller |
| Requests | `/api/Requests…` | Customer and artist sides of a commission |
| Payments | `/api/Requests/PaymentWebhook` | Stripe webhook (anonymous, signature-verified) |
| Admin | `/api/admin/…` | Admin-only: users, artists, seller requests |

## Authentication & authorization

Auth is handled by **Auth0**. The API validates JWT bearer tokens (issuer =
`Auth0:Domain`, audience = `Auth0:Audience`) and enforces **scopes** per
endpoint via authorization policies:

```bash
git clone https://github.com/D4M13N-D3V/art_platform
cd art_platform
```
read:user write:user
read:artist write:artist
read:request write:request
```

### Build and Run with Docker
Admin endpoints require an `Admin` role claim. On the first authenticated
request, the API provisions the user record automatically.

Build the Docker image:
## Configuration

Settings are read from `appsettings.json` (and environment-specific
overrides), or from environment variables using the standard .NET
double-underscore convention (e.g. `Database__password`, `Auth0__Domain`).

**Never commit real secrets.** Copy the template and fill in your own values
locally:

```bash
docker build -t art-platform -f ./src/ArtPlatform.API/Dockerfile --force-rm .
cp src/comissions.app.api/appsettings.example.json src/comissions.app.api/appsettings.json
```

Run the Docker container:
| Key | Required | Description |
| --- | --- | --- |
| `Database:Host` / `:Port` / `:Database` | – | Postgres connection (sensible local defaults) |
| `Database:username` / `:password` | ✅ | Postgres credentials — the app fails fast if unset |
| `Database:RunMigrationsOnStartup` | – | `true` to apply EF migrations on boot (default `false`) |
| `Auth0:Domain` / `:Audience` | ✅ | Token issuer and API audience |
| `Auth0:ClientId` / `:ClientSecret` | – | Used by the Swagger UI OAuth login |
| `Stripe:ApiKey` / `:WebHookSecret` | – | Required only for payment / payout / webhook flows |
| `Novu:ApiKey` | – | Required only for notifications |
| `Storage:ImgCdn:ApiKey` | – | Only if using the imgcdn storage provider |
| `Cors:AllowedOrigins` | – | Comma-separated allow-list (e.g. `http://localhost:3000`) |

## Getting started (local)

### Prerequisites

- [.NET 8 SDK](https://dotnet.microsoft.com/download)
- A PostgreSQL 15 database (Docker is easiest)
- An Auth0 tenant with a custom API + the scopes listed above

### 1. Start Postgres

```bash
docker run -p 8080:80 art-platform
docker run -d --name comissions-pg \
-e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=comissionsapp -p 5432:5432 postgres:15
```

The API should be accessible at `http://localhost:8080`.

## Configuration
### 2. Configure

Application settings are read from `appsettings.json` (and environment-specific
overrides). **Do not commit real secrets.** Copy the template and fill in your
own values locally, or supply them via environment variables / a secret store:
Copy `appsettings.example.json` to `appsettings.json` and fill in your Auth0
values, or export environment variables:

```bash
cp src/comissions.app.api/appsettings.example.json src/comissions.app.api/appsettings.json
export Database__username=postgres
export Database__password=postgres
export Database__RunMigrationsOnStartup=true
export Auth0__Domain="https://YOUR_TENANT.us.auth0.com/"
export Auth0__Audience="https://api.comissions.app"
```

Secrets configured via this file or env vars include:
### 3. Run

| Key | Description |
| --- | --- |
| `Database:username` / `Database:password` | Postgres credentials (required — the app fails to start if unset) |
| `Stripe:ApiKey` / `Stripe:WebHookSecret` | Stripe secret key and webhook signing secret |
| `Auth0:ClientId` / `Auth0:ClientSecret` | Auth0 application credentials |
| `Storage:ImgCdn:ApiKey` | imgcdn upload key |
| `Novu:ApiKey` | Novu notifications key |
```bash
dotnet run --project src/comissions.app.api/comissions.app.api.csproj
```

Environment variables use the standard .NET double-underscore convention,
e.g. `Database__password`, `Stripe__ApiKey`.
The API listens on `http://localhost:5290` and Swagger UI is at
`http://localhost:5290/swagger`. With `RunMigrationsOnStartup=true` the schema
is created automatically on first boot.

## Usage
### Database migrations

Describe how to use your API and any specific details or considerations that users need to be aware of.
Migrations live in `src/comissions.app.api/Migrations`. In production, prefer
running them out-of-band via the migrator project rather than on app startup:

## Swagger UI
```bash
dotnet run --project src/comissions.app.database.migrator
```

The API is documented using Swagger UI. Once the application is running, you can access the Swagger UI at:
## Docker

```plaintext
http://localhost:8080/swagger
```bash
docker build -t comissions-app-core-api -f src/comissions.app.api/Dockerfile .
docker run -p 8080:8080 \
-e Database__Host=... -e Database__username=... -e Database__password=... \
-e Auth0__Domain=... -e Auth0__Audience=... \
comissions-app-core-api
```

This provides an interactive interface for testing and exploring your API endpoints.
Released images are published to GitHub Container Registry:
`ghcr.io/d4m13n-d3v/comissions-app-core-api`.

## CI/CD

GitHub Actions workflows under `.github/workflows`:

| Workflow | Purpose |
| --- | --- |
| `ci.yml` | Build the API + migrator, build the Docker image, Trivy filesystem scan |
| `codeql.yml` | CodeQL static analysis (C#) |
| `gitleaks.yml` | Secret scanning across full history |
| `release.yml` | GitVersion tag → Trivy-gated GHCR image publish → GitHub Release |
| `sdk-publish.yml` | Publish the C# and JavaScript SDKs to GitHub Packages |

Dependencies are kept current by **Dependabot** (NuGet, GitHub Actions,
Docker). Versioning follows [GitVersion](https://gitversion.net/) using
conventional-commit messages.

## Contributing

If you would like to contribute to the project, please follow the guidelines in [CONTRIBUTING.md](CONTRIBUTING.md).
Use conventional-commit messages (`feat:`, `fix:`, `chore:`, …) — they drive
version bumps. Open a pull request against `main`; CI, CodeQL, and the secret
scan must pass.

## License

This project is licensed under the [License Name] - see the [LICENSE.md](LICENSE.md) file for details.
See [LICENSE.md](LICENSE.md).
Loading