# Socialize

Socialize is an organization-owned, workspace-based workflow application for social media content review, revision, approval, and publication readiness.

It is not a public social network. The product is for internal teams, providers, and client approvers coordinating content work before publication.

## Monorepo

- Backend: .NET 10 Web API in `backend/src/Socialize.Api`
- Backend tests: `backend/tests/Socialize.Tests`
- Frontend: Vue 3 + Vite + Vuetify + Pinia in `frontend`
- API contract: OpenAPI snapshot in `shared/openapi`
- Deployment: Docker Compose + Caddy
- Agentic workflow: specs, task files, and prompt templates under `docs`

## Local Development

Terminal 1:

```bash
./scripts/start-infrastructure.sh
./scripts/dev-backend.sh
```

Terminal 2:

```bash
./scripts/dev-frontend.sh
```

Frontend:

```txt
http://localhost:5173
http://<this-machine-lan-ip>:5173
```

Backend:

```txt
http://localhost:5080
http://<this-machine-lan-ip>:5080
```

Swagger UI:

```txt
http://localhost:5080/api
```

## Update Frontend API Types

The backend must be running first.

```bash
./scripts/update-openapi.sh
```

This writes:

```txt
shared/openapi/openapi.json
frontend/src/api/schema.d.ts
```

## Docker Compose

```bash
docker compose up --build
```

Then open:

```txt
http://localhost:8080
http://<this-machine-lan-ip>:8080
```

For preprod deployment, configure the `POSTGRES_PASSWORD`, `RESEND_API_KEY`,
`RESEND_FROM_EMAIL`, and `JWT_SIGNING_KEY` Gitea secrets.
The deploy workflow writes the remote `.env` file and syncs `deploy/compose.yml`
before running the server deploy script.
Use the raw Resend API key value for `RESEND_API_KEY`, without a `Bearer ` prefix.

## Preprod Observability

The optional observability overlay runs a self-hosted Grafana stack for preproduction:

- Grafana `13.0.1`: dashboards
- Prometheus `v3.11.3`: metrics and local alert rules
- Loki `3.7.1`: Docker/container logs
- Tempo `2.10.3`: traces
- Grafana Alloy `v1.16.0`: OTLP receiver and Docker log collector

Start the app with observability:

```bash
docker compose -f deploy/compose.yml -f deploy/observability/compose.observability.yml up -d
```

Grafana is exposed at:

```txt
http://127.0.0.1:3000
```

Default credentials are `admin` / `admin` unless `GRAFANA_ADMIN_USER` and
`GRAFANA_ADMIN_PASSWORD` are set. Set `GRAFANA_HTTP_BIND=0.0.0.0` only when the
preprod network boundary is trusted or protected by a reverse proxy/VPN.

Set a non-default `GRAFANA_ADMIN_PASSWORD` before exposing Grafana outside the
host. Prometheus alert rules are provisioned under
`deploy/observability/prometheus/rules/`; notification delivery is intentionally
left to the preprod operations environment.

## Solution

```bash
dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
```

## Frontend Build

```bash
cd frontend
npm run build
```

## Database Diagram

Start PostgreSQL, then generate a local schema diagram:

```bash
./scripts/generate-db-diagram.sh
```

The script writes an HTML viewer, SVG, PNG, and Graphviz source under:

```txt
.artifacts/db-diagrams/
```

Use `DATABASE_URL`, `PGPASSWORD`, or `~/.pgpass` to provide local database credentials.
When using the repository infrastructure script, the diagram script can read from the
running `socialize-postgres` container directly.

## Agentic Workflow

Start here:

```txt
docs/AGENTIC_WORKFLOW.md
```

Use feature specs, task files, and prompt templates instead of asking agents to work from vague chat history.