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

# 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.

Build and test

./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:

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	Modules, request flow, data model, external dependencies
Configuration	Every environment variable, secret handling, local setup
Deployment	Gitea Actions pipeline, Docker image, server layout
Development	Conventions, testing, adding a parser or endpoint
Troubleshooting	MongoDB, 401s, common startup failures
API reference	Per-domain endpoint documentation
RSS parsers	Sources, scheduling, deduplication
Email reports	Sending generated reports by email
Facebook setup	App, page tokens and lead collection

Historical specs, superseded API revisions and design notes live in docs/archive/.

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 before adding any new configuration value.