How angeldenom/directes-catala works
Project Type and Purpose
• The project is a full-stack web application with two main parts: an API server and a front-end client.
• Its purpose is to serve as a portal (twitch.cat) that aggregates Twitch streams in Catalan, applies filters based on language and engagement criteria, and provides features like dark mode, public statistics (using Umami), and integration with SafeTwitch.
• The README outlines key functionalities such as filtering based on provided lists, PWA support, and potential integration points for additional content and user subscription features.
Analyzing the File Structure
• Notice the top-level directories: "api" and "front".
• The "api" directory contains Go source files (main.go, handlers) and configuration files (Dockerfile, docker-compose.yml, go.mod). It also holds important text files (llista_altres.txt and llista_eliminats.txt) that are used for filtering channels.
• The "front" directory uses Next.js for the UI, with a well-organized structure that includes app pages (e.g., codi-obert, contacte, informa, missió), components, and static assets. Files like next.config.mjs, package.json, and a custom Tailwind config indicate a modern front-end stack.
• Additionally, there are overarching deployment scripts and docker-compose files (deploy.sh, docker-compose.yml) that suggest container orchestration for easy deployment.
Examining the README for Architectural Insights
• The README explicitly states that the project is containerized via docker-compose.
• It clearly differentiates the two parts: the API (in Go) and the front-end (in Next.js using shadcn/ui).
• It mentions integration with external systems – for instance, the SafeTwitch instance and analytics via Umami.
• This information, along with the filtering mechanism via text files stored in the API, guides us on how these components interact.
a. Main Components:
• API Container: Built in Go, handling HTTP requests, filtering channels (using llista_altres.txt and llista_eliminats.txt), and serving REST endpoints.
• Front-End Container: Built with Next.js and shadcn/ui, responsible for rendering the user interface and handling client-side logic.
• Data Sources: Text files that drive the filtering logic (llista_altres.txt and llista_eliminats.txt).
• External Services:
• SafeTwitch integration for opening streams on a separate instance.
• Umami for public analytics/statistics.
• Possibly Twitch itself as an external dependency for live streaming data.
• Docker Infrastructure: Containers orchestrated via docker-compose to manage multi-container deployment, along with deployment scripts (deploy.sh).
b. Relationships and Interactions:
• The Front-End communicates with the API over HTTP/REST calls.
• The API accesses internal file-based data (the two lists) for filtering logic.
• Both containers are networked together by docker-compose, ensuring they can communicate.
• External interactions include redirecting or linking to third-party services (SafeTwitch, Umami, and the Twitch platform).
c. Architectural Patterns and Design Principles:
• Separation of Concerns: Clear division between backend (API) and frontend (Next.js) components.
• Containerization: Both main components run within Docker containers for isolation and simplified deployment.
• Extensibility: The API’s usage of filter lists indicates a design prepared for dynamic content management and possible future enhancement (such as user-specific features).
d. Relevant Technologies, Frameworks, and Libraries:
• API: Go language, likely using standard packages for HTTP handling with a Docker environment.
• Front-End: Next.js, React (with TypeScript), Tailwind CSS, and shadcn/ui, which are all clearly integrated in the “front” directory.
• Docker & Docker Compose: For building and orchestrating the separate containers.
• External Services: References to SafeTwitch and Umami.
Elements
• Use clear labels for each component:
• “Front-End (Next.js)” for the UI container.
• “API Server (Go)” for the backend container.
• “Docker Compose Orchestration” to denote container management.
• “Filter Data (Text Files)” within the API.
• “External Services” for Twitch, SafeTwitch, and Umami.
• From the Front-End to the API server (to show API calls).
• From the API server to the internal filter data (to indicate data usage for filtering).
• From both main components to External Services (illustrating dependency or integration).
• Data flow directions, especially the requests and responses between UI and API.
• Inside the API container, show a connection to “Filter Data Files” (llista_altres.txt and llista_eliminats.txt).
• External service components (e.g., “Twitch Platform”, “SafeTwitch”, “Umami”) connected with directional lines where applicable.