How th0th/poeticmetric works
Project Type & Purpose
• PoeticMetric is an open-source, privacy-first website analytics tool. It replaces traditional analytics (like Google Analytics) with a self-hosted alternative that does not track personal data or use cookies.
• The project is a full-stack application comprising both a frontend (built with modern JavaScript/TypeScript frameworks) and a backend (written in Go), with supporting Docker configurations and scripts for self-hosting.
File Structure Analysis
• Two top-level directories: “frontend” and “backend.”
– The “frontend” directory contains pages, components, hooks, contexts, and documentation for building the user interface. It uses Next.js (as seen in the pages, next.config.js, and TypeScript types) to deliver the web app.
– The “backend” directory is structured into several submodules organized with commands (like “migrator,” “restapi,” “worker,” “scheduler”) and a rich “pkg” folder. This indicates a robust backend providing REST endpoints, background jobs (workers, schedulers), email templating, database migrations for both Postgres and ClickHouse, and integration with external services.
• Additional directories and files (e.g., Dockerfiles, docker-compose.yaml, self-hosted configurations, CI workflows) show that containerization, deployment automation, and testing are key parts of the project.
Key Architectural Components
a. Frontend:
• UI Layer built with React/Next.js, containing multiple component folders (like “Home”, “BlogPage”, “SiteReports”, “Team”) and contexts (e.g., AuthContext, LayoutContext) to manage state.
• Static assets, documents, and user-facing pages.
b. Backend:
• REST API: Organized under backend/cmd/restapi and further subdivided in backend/pkg/restapi with modules for users, organizations, sites, events, and site reports.
• Services and business logic: Separated by domain (site, user, organization, reports, events) to handle core functionality.
• Background Jobs / Workers: Commands like “worker” and “scheduler” to process asynchronous tasks (such as sending email notifications, processing events, and handling trial periods).
• Database Migrations & Data Layer: Migrations for both PostgreSQL and ClickHouse suggest dual-database integration for potentially transactional data and analytical workload.
• Email & Notifications: Email templates and a module for managing email sending and notifications.
• External Integrations: Modules and packages for Stripe (billing), Google (OAuth, Search Console), Mailbluster, RabbitMQ (for message queuing), Redis, and Sentry for error reporting.
c. Infrastructure:
• Docker & Self-hosting: Dockerfile(s) in both “frontend” and “backend”, docker-compose.yaml, and a self-hosted directory indicate containerized deployment.
• CI/CD workflows in the “.github” folder for testing, publishing, and deploying.
• Under Frontend, add subcomponents:
– Pages & Components (e.g., user authentication, site reporting dashboards, blog, settings)
– Contexts/Hooks for state management (auth, layout, reports, etc.)
– REST API Server: Covering endpoints for users, organizations, sites, events, and reports.
– Background Services: Worker processes, scheduler, and migrator modules.
– Data Layer: Illustrate relational databases such as PostgreSQL and analytical databases like ClickHouse.
– Integration Services: Email (with templates), third-party integrations (Stripe for billing, Google OAuth/Search Console, Mailbluster), RabbitMQ/Redis for caching and messaging.
– Environment & Configuration Management: Docker orchestration, environment files, CI configurations.
– Frontend communicates with the Backend REST API.
– Backend interacts with Databases, External Services (e.g., Stripe, Google), and background job queues.
Architectural Patterns & Design Principles
• Separation of concerns: Clear division between presentation (Frontend) and business logic/services (Backend).
• Modular design: The backend is further broken into organized packages (e.g., restapi, service, worker) for maintainability and scalability.
• Containerization & self-hosting: Emphasize the role of Docker and orchestration in deploying the application.
• Event-driven processes: Background workers and schedulers imply asynchronous processing.
• API-first approach: REST API endpoints facilitate frontend-backend communication.