96 lines
3.6 KiB
Markdown
96 lines
3.6 KiB
Markdown
# 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.
|