{"id":34636705,"url":"https://github.com/fullstack-pw/demo-apps","last_synced_at":"2026-05-26T22:33:08.207Z","repository":{"id":281722363,"uuid":"946185984","full_name":"fullstack-pw/demo-apps","owner":"fullstack-pw","description":null,"archived":false,"fork":false,"pushed_at":"2026-02-05T08:13:39.000Z","size":5117,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-05T19:56:51.078Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fullstack-pw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-10T18:41:45.000Z","updated_at":"2026-01-17T13:19:45.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6ad9e7f-c9e3-4158-a5ae-75d46fc2d848","html_url":"https://github.com/fullstack-pw/demo-apps","commit_stats":null,"previous_names":["fullstack-pw/demo-apps"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/fullstack-pw/demo-apps","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-pw%2Fdemo-apps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-pw%2Fdemo-apps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-pw%2Fdemo-apps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-pw%2Fdemo-apps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fullstack-pw","download_url":"https://codeload.github.com/fullstack-pw/demo-apps/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fullstack-pw%2Fdemo-apps/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33542350,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-24T17:02:24.659Z","updated_at":"2026-05-26T22:33:08.200Z","avatar_url":"https://github.com/fullstack-pw.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Fullstack Microservices Messaging System\n\nA scalable, distributed system for processing and transforming messages with image-to-ASCII art capabilities.\n\n## Overview\n\nThis project demonstrates a modern microservices architecture that processes messages through a pipeline of services. The system allows users to submit text descriptions, automatically finds relevant images, and transforms them into ASCII art representations.\n\n![Ascii gen](ascii.gif)\n\n## System Architecture\n\nThe system consists of multiple microservices communicating via message queues:\n\n![Arch](demo-apps.svg)\n\n### Complete Message Flow\n\n1. **User Request**: User accesses `ascii-frontend` and submits a query (e.g., \"kubernetes\")\n2. **Enqueuer Processing**:\n   - Receives the query via REST API (`POST /add`)\n   - Searches Google Images using Chromium headless browser\n   - Picks the first suitable image URL\n   - Publishes message with image URL to NATS queue (`{ENV}.queue-{QUEUE_NAME}`)\n   - Subscribes to result queue (`{ENV}.result-queue`) to wait for ASCII art response\n3. **Memorizer Processing**:\n   - Listens to NATS queue for new messages\n   - Downloads the image from the URL\n   - Generates ASCII art (terminal, file, and HTML formats)\n   - Stores the ASCII art output in Redis (with environment prefix: `{ENV}:{MESSAGE_ID}:ascii_*`)\n   - Publishes the result back to NATS result queue\n4. **Enqueuer Response**:\n   - Receives ASCII art result from NATS result queue\n   - Returns complete response to the user (including image URL and ASCII art)\n5. **Writer Storage**:\n   - Monitors Redis for new entries\n   - Retrieves processed messages with ASCII art\n   - Stores everything in PostgreSQL (environment-specific tables)\n   - Provides query endpoints for historical data\n\n### Technology Stack\n\n- **Communication**: NATS for message queuing\n- **Storage**: Redis for temporary storage, PostgreSQL for persistent storage\n- **Deployment**: Kubernetes with Kustomize configurations\n- **Observability**: OpenTelemetry for distributed tracing\n- **Testing**: Cypress for end-to-end testing\n\n## Services\n\n### Enqueuer\n\nThe entry point for the system. Receives message requests, searches for relevant images, and publishes messages to NATS.\n\n**Key Features:**\n- RESTful API for accepting messages\n- Image search capability using web scraping\n- Message publishing with trace context propagation\n- Health check endpoints\n\n### Memorizer\n\nProcesses messages from NATS, stores them in Redis, and converts images to ASCII art.\n\n**Key Features:**\n- NATS subscription with environment-based routing\n- Python-based image-to-ASCII conversion\n- Multiple ASCII formats (terminal, file, HTML)\n- Redis storage with environment prefixing\n\n### Writer\n\nSubscribes to processed messages from Redis, stores them in PostgreSQL, and provides query endpoints.\n\n**Key Features:**\n- Environment-specific database tables\n- RESTful API for querying stored messages\n- ASCII art retrieval endpoints\n- Database connection pooling and retry logic\n\n### ASCII Frontend\n\nWeb application that provides a user interface for submitting message descriptions and viewing ASCII art.\n\n**Key Features:**\n- React-based user interface\n- Environment-aware API communication\n- Multiple ASCII art view modes (HTML and Text)\n- Copy/download functionality for generated art\n\n## Setup \u0026 Installation\n\n### Prerequisites\n\n- Docker and Docker Compose\n- Kubernetes cluster (for production deployment)\n- Go 1.23.1\n- Node.js (for frontend and Cypress tests)\n\n### Local Development\n\n1. Clone the repository:\n   ```bash\n   git clone https://github.com/fullstack-pw/demo-apps.git\n   cd demo-apps\n   ```\n\n2. Start the local environment:\n   ```bash\n   docker-compose up -d\n   ```\n\n3. Run the services individually for development:\n   ```bash\n   # Enqueuer\n   cd apps/enqueuer\n   go run main.go\n   \n   # Memorizer\n   cd apps/memorizer\n   go run main.go\n   \n   # Writer\n   cd apps/writer\n   go run main.go\n   \n   # ASCII Frontend\n   cd apps/ascii-frontend\n   npm install\n   npm run dev\n   ```\n\n## Development \u0026 Testing\n\n### Running Tests\n\nThe project uses Cypress for end-to-end testing:\n\n```bash\n# Install dependencies\nnpm install\n\n# Run Cypress tests in development environment\nnpm run cypress:dev\n\n# Run Cypress tests in staging environment\nnpm run cypress:stg\n\n# Run Cypress tests in production environment\nnpm run cypress:prod\n\n# Run Cypress tests in local environment\nnpm run cypress:local\n```\n\n### Adding New Tests\n\nTest files are located in the `cypress/e2e/` directory. The system provides custom Cypress commands defined in `cypress/support/commands.js` for common operations like sending messages and verifying processing.\n\n## Deployment\n\nThe project uses Kubernetes with Kustomize for deployment. Each service has base configurations and environment-specific overlays:\n\n```\napps/\n├── enqueuer/\n│   └── kustomize/\n│       ├── base/\n│       ├── overlays/\n│           ├── dev/\n│           ├── stg/\n│           └── prod/\n├── memorizer/\n│   └── kustomize/\n│       └── ...\n├── writer/\n│   └── kustomize/\n│       └── ...\n└── ascii-frontend/\n    └── kustomize/\n        └── ...\n```\n\n### Deploying to an Environment\n\n```bash\n# Deploy to development\nkubectl apply -k apps/enqueuer/kustomize/overlays/dev\nkubectl apply -k apps/memorizer/kustomize/overlays/dev\nkubectl apply -k apps/writer/kustomize/overlays/dev\nkubectl apply -k apps/ascii-frontend/kustomize/overlays/dev\n\n# Deploy to staging or production\nkubectl apply -k apps/*/kustomize/overlays/stg\nkubectl apply -k apps/*/kustomize/overlays/prod\n```\n\nThe project also includes GitHub Actions workflows for CI/CD in `.github/workflows/`.\n\n## API Documentation\n\n### Enqueuer API\n\n- `POST /add`: Add a new message to the queue\n  - Query Parameters:\n    - `queue`: Queue name (default: \"default\")\n  - Request Body:\n    ```json\n    {\n      \"id\": \"optional-message-id\",\n      \"content\": \"Message content or description\",\n      \"headers\": {\n        \"optional-header-key\": \"optional-header-value\"\n      }\n    }\n    ```\n  - Response:\n    ```json\n    {\n      \"status\": \"completed\",\n      \"queue\": \"queue-name\",\n      \"image_url\": \"https://example.com/image.jpg\",\n      \"image_ascii_text\": \"ASCII art text representation\",\n      \"image_ascii_html\": \"\u003cpre\u003eHTML ASCII art\u003c/pre\u003e\"\n    }\n    ```\n\n- `GET /check-memorizer`: Check if a message was processed by memorizer\n  - Query Parameters:\n    - `id`: Message ID\n  - Response:\n    ```json\n    {\n      \"id\": \"message-id\",\n      \"processed\": true\n    }\n    ```\n\n- `GET /check-writer`: Check if a message was stored by writer\n  - Query Parameters:\n    - `id`: Message ID\n  - Response: Returns the stored message with additional metadata\n\n- `GET /ascii/terminal`: Get terminal ASCII art for a message\n  - Query Parameters:\n    - `trace_id`: Trace ID\n  - Response: Plain text ASCII art\n\n- `GET /ascii/html`: Get HTML ASCII art for a message\n  - Query Parameters:\n    - `trace_id`: Trace ID\n  - Response: HTML ASCII art\n\n### Writer API\n\n- `GET /query`: Query for a stored message\n  - Query Parameters:\n    - `id`: Message ID\n  - Response: The stored message with ASCII art references\n\n- `GET /ascii/terminal`: Get terminal ASCII art for a message\n  - Query Parameters:\n    - `id`: Message ID\n  - Response: Plain text ASCII art\n\n- `GET /ascii/file`: Get file ASCII art for a message\n  - Query Parameters:\n    - `id`: Message ID\n  - Response: Plain text ASCII art with download header\n\n- `GET /ascii/html`: Get HTML ASCII art for a message\n  - Query Parameters:\n    - `id`: Message ID\n  - Response: HTML ASCII art\n\n### Health Endpoints\n\nAll services provide the following health endpoints:\n\n- `GET /health`: Overall service health\n- `GET /livez`: Liveness probe\n- `GET /readyz`: Readiness probe\n\n## Contributing\n\n### Code Structure\n\n- `apps/`: Contains all service code\n  - `enqueuer/`: Enqueuer service\n  - `memorizer/`: Memorizer service\n  - `writer/`: Writer service\n  - `ascii-frontend/`: Web frontend\n  - `shared/`: Shared Go packages\n- `cypress/`: End-to-end tests\n- `.github/workflows/`: CI/CD workflows\n\n### Contribution Guidelines\n\n1. Create a feature branch off of main\n2. Make your changes\n3. Run tests to ensure functionality\n4. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstack-pw%2Fdemo-apps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffullstack-pw%2Fdemo-apps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffullstack-pw%2Fdemo-apps/lists"}