# Marketing Parser

Spring Boot service behind the KonturAI marketing platform. It ingests business news
from RSS sources, runs AI-driven marketing analysis and strategy generation over that
corpus, renders the results as PDF/DOCX/Markdown reports, and publishes campaign
content to social networks.

- **Java 21** · **Spring Boot 3.5.5** · **MongoDB** · **MinIO**
- AI providers: **OpenAI**, **Ollama** (self-hosted), **Google Vertex AI** (Imagen/Veo)
- Deployed via **Gitea Actions** to a self-hosted Docker runner

---

## Quick start

```bash
# 1. Provide configuration (see docs/configuration.md)
cp .env.example .env
$EDITOR .env                     # fill in every REQUIRED value

# 2. Supply the Google service-account key (only for image/video generation)
cp /secure/path/google-key.json src/main/resources/keys/google-key.json

# 3. Run
set -a && source .env && set +a
./mvnw spring-boot:run
```

The service listens on `http://localhost:8080`. Interactive API docs are at
`http://localhost:8080/swagger-ui.html`, health at `/api/parser/health`.

> The application **fails fast at startup** if a required secret is missing. That is
> deliberate — see [docs/configuration.md](docs/configuration.md).

## Build and test

```bash
./mvnw clean verify        # unit tests + JaCoCo coverage gate
./mvnw clean package       # build the jar
```

Integration tests boot the full Spring context and need real MongoDB plus the
environment variables above. They are opt-in:

```bash
RUN_INTEGRATION_TESTS=true ./mvnw verify
```

`verify` enforces 80% line coverage on `PostingTaskService`, `JwtService` and
`SocialMediaCredentialsService` (see the JaCoCo rule in `pom.xml`).

## Documentation

| Guide | What it covers |
| --- | --- |
| [Architecture](docs/architecture.md) | Modules, request flow, data model, external dependencies |
| [Configuration](docs/configuration.md) | Every environment variable, secret handling, local setup |
| [Deployment](docs/deployment.md) | Gitea Actions pipeline, Docker image, server layout |
| [Development](docs/development.md) | Conventions, testing, adding a parser or endpoint |
| [Troubleshooting](docs/troubleshooting.md) | MongoDB, 401s, common startup failures |
| [API reference](docs/api/README.md) | Per-domain endpoint documentation |
| [RSS parsers](docs/rss-parsers.md) | Sources, scheduling, deduplication |
| [Email reports](docs/email-reports.md) | Sending generated reports by email |
| [Facebook setup](docs/facebook-setup.md) | App, page tokens and lead collection |

Historical specs, superseded API revisions and design notes live in
[docs/archive/](docs/archive/README.md).

## Repository layout

```
src/main/java/kz/konturai/parser/
├── controller/   REST endpoints (15) + GlobalExceptionHandler
├── service/      Business logic (52) — parsers, AI, reports, posting, targeting
├── model/        MongoDB documents (21)
├── dto/          Request/response payloads (68)
├── repository/   Spring Data Mongo repositories (11)
├── config/       Beans, CORS, Swagger, async executors, typed properties
├── validator/    Request validation
├── enums/        Shared enumerations
├── exception/    Domain exceptions
└── util/         Helpers

deployment/       docker-compose for the production host
docs/             Documentation (see table above)
scripts/          Run helper and smoke-test scripts
.gitea/workflows/ CI/CD pipeline
```

## Security

Never commit credentials. All secrets are supplied through environment variables and
`src/main/resources/keys/google-key.json` is deliberately untracked. See
[docs/configuration.md](docs/configuration.md#secret-handling) before adding any new
configuration value.