diff --git a/docs/content-audit-2025-11.md b/docs/content-audit-2025-11.md new file mode 100644 index 0000000..089ab06 --- /dev/null +++ b/docs/content-audit-2025-11.md @@ -0,0 +1,40 @@ +--- +title: Content Audit — November 2025 +sidebar_position: 99 +--- + +# Content Audit — November 2025 + +This report summarises the documentation clean-up performed in November 2025. Use it as a changelog and as a reference for future audits. + +## Pages removed or archived + +- **Repositories (legacy)** — Retained but explicitly marked as archived and documented when it is safe to delete. No other pages were removed. + +## Pages updated + +| Page | Summary of improvements | +| --- | --- | +| [Intro](./intro.md) | Expanded welcome message, clarified how to navigate MonaDocs, and added a quick-start checklist for new contributors. | +| [Repositories](./repositories/index.mdx) | Documented URL parameters, caching behaviour, authentication options, and accessibility considerations for the interactive listing. | +| [Repositories (legacy)](./repositories/index.md) | Reframed as an archived fallback with clear guidance on decommissioning. | +| [Boteco Pro](./projects/boteco-pro.md) | Replaced placeholder content with product overview, modules, technology landscape, roadmap, and contribution workflow. | +| [Boteco.pt](./projects/boteco-pt/index.md) | Added business objectives, audience, UX guidelines, technical implementation notes, and roadmap. | +| [ArtLeo Creative Spaces](./projects/artleo-creative-spaces/index.md) | Detailed product pillars, reference stack, delivery workflow, and roadmap for the discovery phase. | +| [FACODI](./projects/facodi/index.md) | Clarified value proposition, architecture, compliance stance, and contribution expectations. | +| [Monynha.com](./projects/monynha-com/index.md) | Documented site structure, content standards, operations, and roadmap. | +| [Monynha Online](./projects/monynha-online/index.md) | Captured use cases, configuration options, technical overview, and contribution notes. | +| [MonynhaTech](./projects/monynha-tech/index.md) | Added goals, module breakdown, architecture, editorial workflow, and roadmap. | +| [Sweet Price](./projects/sweet-price/index.md) | Expanded problem statement, capabilities, stack, data governance, and contribution practices. | + +## New pages created + +| Page | Location | Summary | +| --- | --- | --- | +| [Projects Overview](./projects/overview.md) | `docs/projects/overview.md` | Portfolio-level snapshot with status, tech stack, and guidance for proposing new projects. | + +## Next steps + +- Review technology pages during the next sprint to ensure they match current stack decisions. +- Align project roadmaps with the quarterly OKR review and update dates accordingly. +- Instrument analytics dashboards to monitor engagement with newly expanded project pages. diff --git a/docs/intro.md b/docs/intro.md index 8910f74..885e83e 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -4,15 +4,24 @@ sidebar_position: 1 # Welcome to MonaDocs -This is the central documentation hub for **Monynha Softwares**, containing guides, standards, and information about our projects, technologies, and processes. +**MonaDocs** is the central documentation hub for **Monynha Softwares**. It brings together our product vision, architectural decisions, operating standards, and contributor guidance so that every team member and partner can work with the same context. -## What you'll find here +## How to use this site -- **Projects**: Detailed documentation for each project developed by Mona. -- **Technologies**: Guides about the technologies we use. -- **Internal Standards**: Code norms, architecture, and best practices. -- **Guides and Best Practices**: Tutorials and recommendations for development. -- **Contributor Documentation**: How to contribute to our projects. -- **Other Topics**: Topics like UX, accessibility, and data. +- **Projects** – Explore current initiatives, their business goals, feature roadmaps, and implementation details. +- **Technologies** – Review the approved stacks, reference architectures, and hands-on guides for the platforms we rely on. +- **Architecture** – Understand how the monorepo is organised, how services communicate, and how we deploy software. +- **Internal Standards** – Follow our coding conventions, security requirements, UX and accessibility rules, and operational checklists. +- **Contribution** – Learn how we collaborate, from governance to contribution workflows and review processes. +- **Playbooks & Guides** – Find repeatable procedures for delivery, incident response, and other cross-team practices. -Explore the sections in the sidebar for more information. +Use the sidebar or the search bar to jump directly to the topic you need. Each page lists related content so you can keep exploring. + +## Quick start for new contributors + +1. Read the [Contribution Guide](contribution/contributing.md) for branching, review, and release conventions. +2. Familiarise yourself with the [Architecture](architecture/monorepo-structure.md) section to understand our monorepo layout and CI/CD strategy. +3. Review the [Code Conventions](guidelines/code-conventions.md) and [Accessibility Guidelines](guidelines/accessibility.md) before opening your first pull request. +4. Visit the [Projects](projects/overview.md) catalog to see active workstreams and select where you can help. + +If you spot missing information, please open an issue or submit an update—documentation is a shared responsibility. diff --git a/docs/projects/artleo-creative-spaces/index.md b/docs/projects/artleo-creative-spaces/index.md index cead2dd..43ee7e4 100644 --- a/docs/projects/artleo-creative-spaces/index.md +++ b/docs/projects/artleo-creative-spaces/index.md @@ -1,19 +1,49 @@ # ArtLeo Creative Spaces -## Description +## Overview -Art by Monynha +ArtLeo Creative Spaces is a digital platform under active discovery. It aims to connect independent artists with venues that host exhibitions, workshops, and creative residencies. The documentation below captures the current understanding of scope and technical direction so contributors can collaborate consistently. -## Technologies +## Target users -- TypeScript +- Visual artists and makers who need a professional showcase and booking calendar. +- Venue managers responsible for programming art events. +- Curators looking for curated collections and available time slots. -## Repository +## Product pillars -[GitHub: artleo-creative-spaces](https://github.com/Monynha-Softwares/artleo-creative-spaces) +1. **Portfolio publishing** – Responsive galleries, media kits, and artist bios optimised for search engines. +2. **Space discovery** – Location-aware search with filters for availability, amenities, and equipment. +3. **Booking workflow** – End-to-end request, approval, and contract management with notifications. +4. **Community insights** – Dashboards showing attendance, sales, and engagement metrics. -## Features +## Reference technology stack -- Creative and artistic spaces platform -- Platform for artistic expression +The stack will continue to evolve; align with the tech lead before introducing alternatives. +- **Frontend**: Next.js + TypeScript with Tailwind CSS for rapid UI development. +- **Backend**: Supabase (PostgreSQL + Auth) providing database, storage, and row-level security. +- **Integrations**: Stripe for payments, Mapbox for geolocation, Resend for transactional email. +- **Infrastructure**: Vercel preview/production environments orchestrated by GitHub Actions workflows. + +## Delivery workflow + +- **Branching**: `main` (production), `develop` (staging), feature branches per issue. +- **CI/CD**: Automated linting, testing, and preview deployments on pull requests. +- **Monitoring**: Vercel Analytics, Supabase logs, and Sentry for runtime errors. +- **Environments**: Shared staging database seeded weekly; production backups nightly. + +## Roadmap highlights + +| Milestone | Focus | ETA | +| --- | --- | --- | +| Artist onboarding UX | Simplify signup, add progressive profile completion | 2025-Q1 | +| Venue CRM tooling | Improve lead tracking, add automated follow-ups | 2025-Q2 | +| Marketplace launch | Public discovery experience with SEO landing pages | 2025-Q3 | + +## How to contribute + +1. Check the open issues labelled `help wanted` in the repository. +2. Discuss major UX or architectural changes with the product owner before implementation. +3. Follow the shared [code conventions](../../guidelines/code-conventions.md) and include accessibility acceptance criteria in every PR. +4. Provide screenshots or Loom videos for UI updates and ensure English/Portuguese copy parity. diff --git a/docs/projects/boteco-pro.md b/docs/projects/boteco-pro.md index 3af1751..dd7b8fc 100644 --- a/docs/projects/boteco-pro.md +++ b/docs/projects/boteco-pro.md @@ -1,49 +1,52 @@ --- -title: "Boteco Pro — Project Overview" +title: "Boteco Pro" sidebar_position: 1 --- -This compatibility page points to the canonical project documentation under the `projects` section. +# Boteco Pro -Please visit the canonical page for Boteco Pro: +## Overview -[Boteco Pro — Project Page](/docs/projects/boteco-pro) +Boteco Pro is Monynha Softwares' flagship hospitality management platform. It consolidates point-of-sale, inventory, reservations, and loyalty experiences into a single suite tailored for bars and restaurants in Portugal and beyond. -If you maintain docs links that point to `/docs/projetos/*`, consider updating them to `/docs/projects/*`. +## Customer outcomes -### Planned +- Reduce manual reconciliation by synchronising sales, stock, and accounting data. +- Increase table turnover with smart reservations, waitlist management, and QR ordering. +- Grow repeat business through integrated loyalty programs and segmented campaigns. -- Advanced analytics dashboards -- Loyalty / rewards system -- Multi-location management -- Web-based ordering integration +## Product modules -## Development status +1. **Point of Sale** – Multi-terminal POS with offline mode, receipt customisation, and tipping. +2. **Inventory & Procurement** – Supplier catalogues, purchase orders, and automated stock alerts. +3. **Reservations & Floor Management** – Table layouts, pacing controls, and guest communications. +4. **Loyalty & Marketing** – Tiered rewards, email/SMS campaigns, and customer analytics dashboards. +5. **Insights** – Real-time KPI cockpit covering revenue, labour costs, and menu performance. -- Current phase: Beta testing with select partners -- Next milestone: v1.1 (enhanced reporting) -- Target for full v1.0: Q1 2026 +## Technology landscape -## Setup & local development +- **Mobile**: Flutter app for in-venue operations and tablet ordering. +- **Backend**: Convex for realtime data synchronisation, complemented by serverless functions for heavy processing. +- **Integrations**: Fiscal printers, payment gateways, delivery platforms, and accounting tools (TIC, Sage, Xero). +- **Infrastructure**: Containerised services orchestrated via Coolify with GitHub Actions CI/CD. -### Prerequisites +## Deployment model -- Flutter SDK (3.x+) -- Dart SDK (2.19+) -- Convex account / project setup +- Tenants are provisioned per venue with region-aware configurations (currency, tax rules). +- Multi-environment setup: `production`, `staging`, `sandbox` for demos. +- Automated backups and migration scripts maintained in the `infra/` directory of the main repository. -### Quick start +## Roadmap -1. Clone the repository +| Milestone | Description | Status | +| --- | --- | --- | +| Analytics v1.1 | Expand dashboards with labour cost tracking and anomaly detection. | In QA | +| Loyalty 2.0 | Introduce card-linked offers and partner marketplace integrations. | Development | +| Delivery Hub | Unified view for delivery platforms (Uber Eats, Glovo, Bolt Food). | Discovery | -```bash -git clone https://github.com/Monynha-Softwares/Boteco-Pro.git -cd boteco-pro -``` - -1. Install dependencies - -```bash -flutter pub get -``` +## Contribution workflow +1. Review open issues labelled `feature`, `bug`, or `research` before picking up work. +2. Ensure database migrations include backward-compatibility notes. +3. Add end-to-end tests for mission-critical flows (orders, reservations, loyalty redemption). +4. Provide bilingual release notes (PT/EN) summarising changes for venue managers. diff --git a/docs/projects/boteco-pt/index.md b/docs/projects/boteco-pt/index.md index 69cbb2e..ea84386 100644 --- a/docs/projects/boteco-pt/index.md +++ b/docs/projects/boteco-pt/index.md @@ -1,19 +1,53 @@ # Boteco.pt -## Description +## Overview -Boteco Pro: Complete solution for bars and restaurants. +Boteco.pt is the Portuguese marketing site for the Boteco hospitality platform. It communicates product value, captures inbound leads, and provides support resources for bar and restaurant owners evaluating Boteco Pro. -## Technologies +## Objectives -- TypeScript +- Present core modules—POS, inventory, loyalty, and analytics—in Portuguese with local pricing. +- Drive demo requests via integrated CRM forms and calendaring links. +- Highlight testimonials, partner integrations, and regulatory compliance updates. +- Offer downloadable brochures, FAQs, and help-centre entry points. -## Repository +## Audience -[GitHub: boteco.pt](https://github.com/Monynha-Softwares/boteco.pt) +- Owners and managers of bars, cafés, and small restaurant chains. +- Franchise operators comparing management software. +- Channel partners and resellers seeking co-marketing assets. -## Features +## Content & UX guidelines -- Full management system for bars and restaurants -- Integrated solutions for the hospitality sector +- Provide parity between Portuguese and English copy, prioritising accessibility (WCAG AA) and inclusive language. +- Include structured data for product, FAQ, and local business to improve SEO visibility. +- Optimise for Core Web Vitals—especially Largest Contentful Paint and Cumulative Layout Shift. +- Ensure forms support keyboard navigation and screen readers; validate inputs with clear error messaging. +## Technical implementation + +- **Framework**: Next.js with static generation for marketing pages and server-side rendering for dynamic lead forms. +- **Styling**: Tailwind CSS + custom design tokens defined in `packages/ui`. +- **Integrations**: HubSpot (lead capture), Resend (transactional email), Google Tag Manager (analytics consent). +- **Hosting**: Vercel production + preview deployments from pull requests. + +## Operations + +- Content updates are managed through MDX sections; keep components localised under `apps/web/content`. +- For campaign-specific pages, create new routes under `/campanhas` with analytics tagging. +- Use the shared [UX Guidelines](../../guidelines/ux-guidelines.md) for motion, colour contrast, and iconography. + +## Roadmap + +| Initiative | Description | Status | +| --- | --- | --- | +| Case study hub | Publish success stories for Portuguese venues with video embeds. | In progress | +| Pricing calculator | Interactive ROI calculator tailored to venue size and modules. | Planned | +| Knowledge centre | Integrate support articles sourced from Freshdesk. | Planned | + +## Contribution checklist + +1. Review open issues tagged `website` in the main repository. +2. Coordinate with marketing for copy approval before merging changes. +3. Attach Lighthouse and axe accessibility reports to pull requests touching UI. +4. Provide localisation keys and translations for any new text strings. diff --git a/docs/projects/facodi/index.md b/docs/projects/facodi/index.md index d37ba77..66161f9 100644 --- a/docs/projects/facodi/index.md +++ b/docs/projects/facodi/index.md @@ -1,19 +1,46 @@ # FACODI -## Description +## Overview -FACODI — Community Digital College — https://facodi.pt +FACODI (Faculdade Comunitária Digital) is an online learning environment offering asynchronous courses, live cohorts, and mentorship for Portuguese-speaking communities. The platform focuses on accessibility, affordability, and community-driven learning. -## Technologies +## Value proposition -- Python +- Democratise access to technology education and entrepreneurial training. +- Provide modular curricula aligned with local job market needs. +- Build a mentorship network pairing students with industry professionals. -## Repository +## Core experience -[GitHub: facodi.pt](https://github.com/Monynha-Softwares/facodi.pt) +1. **Learning paths** – Sequenced modules combining video, readings, and interactive assessments. +2. **Community spaces** – Forums, study groups, and mentor office hours with moderation tools. +3. **Certification** – Verifiable completion certificates and digital badges. +4. **Partner programs** – White-label offerings for NGOs, schools, and municipalities. -## Features +## Platform architecture -- Community educational platform -- Digital learning resources +- **Backend**: Django with PostgreSQL, leveraging Django REST Framework for APIs. +- **Frontend**: Next.js client consuming REST endpoints and rendering MDX course content. +- **Realtime**: Pusher channels for live classrooms and chat. +- **Analytics**: Metabase dashboards visualising engagement, retention, and graduation metrics. +## Compliance & accessibility + +- Meets WCAG 2.1 AA with screen-reader friendly navigation and captioned media. +- Stores learner data within EU data centres and respects GDPR consent requirements. +- Implements secure exam proctoring using timed assessments and device fingerprinting. + +## Roadmap + +| Initiative | Goal | Status | +| --- | --- | --- | +| Mentor marketplace | Match learners with mentors using availability calendars. | Development | +| Offline access | Allow course downloads within the mobile app. | Discovery | +| Scholarship engine | Automate scholarship eligibility and onboarding. | Planned | + +## Contribution guidelines + +- Coordinate curriculum changes with the academic board before editing content repositories. +- Add unit tests for Django services and Playwright regression tests for key learner journeys. +- Provide Portuguese and English copy when altering UI strings. +- Document data migrations and run them against staging before requesting production deploys. diff --git a/docs/projects/monynha-com/index.md b/docs/projects/monynha-com/index.md index e6d7af4..388678c 100644 --- a/docs/projects/monynha-com/index.md +++ b/docs/projects/monynha-com/index.md @@ -1,19 +1,55 @@ # Monynha.com -## Description +## Overview -Monynha Softwares' institutional website — tailor-made software and AI solutions. +Monynha.com is the institutional website presenting Monynha Softwares' services, portfolio, and culture. It supports lead generation, recruiting, and brand positioning. -## Technologies +## Strategic goals -- TypeScript -- Next.js (likely) +- Highlight core service lines (custom software, AI solutions, digital strategy) with case studies and metrics. +- Provide a clear call-to-action for consultations, with integration to the sales CRM. +- Share company culture, hiring needs, and benefits for prospective teammates. +- Host multilingual content (Portuguese and English) to support international expansion. -## Repository +## Information architecture -[GitHub: Monynha-com](https://github.com/Monynha-Softwares/Monynha-com) +1. **Home** – Value proposition, marquee projects, testimonials. +2. **Services** – Detailed explanation of offerings with process outlines. +3. **Industries** – Sector-specific stories and success indicators. +4. **Resources** – Blog, whitepapers, and event recordings. +5. **Company** – About, team, careers, contact. -## Features +## Content guidelines -- Institutional website -- Presentation of software and AI solutions +- Maintain inclusive, gender-neutral language in both PT and EN. +- Reference quantifiable outcomes (KPIs, timelines) when describing case studies. +- Provide alt text for every media asset and transcriptions for embedded videos. +- Use structured data (Organisation, Breadcrumb, Article) for SEO performance. + +## Technical implementation + +- **Framework**: Next.js with incremental static regeneration for marketing pages. +- **CMS**: Content managed via MDX files stored in the repository; integrate with Notion exports where relevant. +- **Styling**: Shared design system components from `packages/ui` with dark/light theme support. +- **Analytics**: Plausible + server-side events forwarded to the CRM. + +## Operations + +- Deployments occur through GitHub Actions -> Vercel after automated accessibility and performance checks. +- Localisation files live under `apps/web/i18n`; update both PT and EN namespaces in each pull request. +- Maintain the newsroom/newsletter archive and archive deprecated campaigns in `/legacy`. + +## Roadmap + +| Initiative | Description | Status | +| --- | --- | --- | +| Case study refresh | Expand portfolio with interactive storytelling components. | In progress | +| Career portal | Integrate greenhouse-style candidate portal with ATS sync. | Planned | +| Accessibility sweep | Quarterly audits with screen reader testing reports. | Recurring | + +## Contribution checklist + +1. Coordinate with marketing for copy approvals and legal disclaimers. +2. Include Lighthouse, axe, and performance budgets when submitting UI changes. +3. Update translations and run `npm run build` locally before requesting review. +4. Attach visual diffs or screenshots showing PT and EN variants. diff --git a/docs/projects/monynha-online/index.md b/docs/projects/monynha-online/index.md index 7213833..8026e4d 100644 --- a/docs/projects/monynha-online/index.md +++ b/docs/projects/monynha-online/index.md @@ -1,18 +1,46 @@ # Monynha Online -## Description +## Overview -https://monynha.online +Monynha Online provides a lightweight, customisable landing page template used for product previews, campaigns, and microsites. It acts as the default fallback experience when a dedicated site is not yet available. -## Technologies +## Use cases -- TypeScript +- Rapid launch pages for beta waitlists or feature previews. +- Temporary redirects during migration projects. +- Campaign-specific microsites with tailored messaging and tracking. -## Repository +## Customisation options -[GitHub: MonynhaOnline-Default-Page](https://github.com/Monynha-Softwares/MonynhaOnline-Default-Page) +- Configurable hero sections, feature highlights, and pricing blocks defined through JSON/MDX data files. +- Theme tokens (colours, typography, spacing) aligned with the design system. +- Optional language switcher and locale-aware routing. +- Integrations for newsletter signup (Mailchimp), contact forms (HubSpot), and analytics (Plausible). -## Features +## Technical overview -- Default online presence for Monynha -- Digital presence +- **Framework**: Next.js with static generation for base pages and API routes for form submissions. +- **Styling**: Tailwind CSS + Radix UI primitives to ensure accessibility. +- **Content**: MDX-powered sections under `content/` plus localisation files in `i18n/`. +- **Deployment**: Vercel previews per branch, production pipeline gated by accessibility checks. + +## Operations + +- Use environment-specific `.env` files to configure API keys—never commit secrets; update `.env.example` when adding new variables. +- Maintain variant configurations in `config/sites/*.ts`; each file represents one microsite. +- Document site-specific assets (logos, illustrations) in the repository README. + +## Roadmap + +| Initiative | Description | Status | +| --- | --- | --- | +| Theme presets | Bundle reusable presets for fintech, SaaS, and education launches. | In progress | +| Component library sync | Automate dependency updates with the shared UI package. | Planned | +| No-code bridge | Provide Airtable/Notion sync to populate content dynamically. | Discovery | + +## Contribution notes + +1. Validate that Lighthouse scores stay above 90 for Performance, Accessibility, and Best Practices. +2. Supply Portuguese and English content for every page variant. +3. Capture screenshots for each viewport breakpoint when updating layout components. +4. Coordinate DNS or redirect changes with the DevOps team before launch. diff --git a/docs/projects/monynha-tech/index.md b/docs/projects/monynha-tech/index.md index ab21bed..1f66bdb 100644 --- a/docs/projects/monynha-tech/index.md +++ b/docs/projects/monynha-tech/index.md @@ -1,18 +1,48 @@ # MonynhaTech -## Description +## Overview -[https://monynha.tech](https://monynha.tech) +MonynhaTech is a public-facing knowledge hub showcasing Monynha Softwares' open-source initiatives, developer tooling, and community events. It aggregates documentation, tutorials, and sandbox projects. -## Technologies +## Goals -- TypeScript +- Provide clear entry points for developers exploring Monynha ecosystems. +- Promote open-source repositories, starter kits, and API references. +- Host community events, workshops, and recordings. +- Encourage contributions by documenting governance and support channels. -## Repository +## Key modules -[GitHub: MonynhaTech](https://github.com/Monynha-Softwares/MonynhaTech) +1. **Resource library** – Tutorials, quickstarts, and code samples with filters by technology. +2. **Event hub** – Calendar of meetups, livestreams, and hackathons with registration links. +3. **Showcase gallery** – Highlights of partner and community projects built with Monynha tooling. +4. **Support centre** – Office hours, Slack/Discord invites, and escalation paths. -## Features +## Technical architecture -- Monynha technology platform -- Tools and resources for developers +- **Frontend**: Next.js with MDX content sourced from the MonaDocs repository via a content pipeline. +- **Search**: Algolia DocSearch for instant retrieval, configured with bilingual indexes. +- **Auth**: GitHub OAuth to unlock interactive sandboxes and comment features. +- **Analytics**: PostHog for product analytics, with anonymised event tracking. + +## Editorial workflow + +- Draft content in Notion or Google Docs, then convert to MDX using the shared writing style guide. +- Run automated copy linting (Vale) and accessibility checks before publishing. +- Tag content with metadata for language, topic, and difficulty level. +- Schedule reviews every quarter to retire or refresh outdated tutorials. + +## Roadmap + +| Initiative | Description | Status | +| --- | --- | --- | +| Interactive playground | Embed StackBlitz-powered sandboxes for API demos. | Development | +| Translation workflow | Automate PT ↔ EN translation sync with Lokalise. | Planned | +| Community badges | Introduce recognition program for contributors. | Discovery | + +## Contribution guidelines + +- Follow the [Contribution Guide](../../contribution/contributing.md) and submit PRs with preview links. +- Provide both Portuguese and English content; avoid machine-only translations without review. +- Include accessibility acceptance criteria in issues and pull requests. +- Capture analytics impacts (new events, tags) in release notes. diff --git a/docs/projects/overview.md b/docs/projects/overview.md new file mode 100644 index 0000000..964b043 --- /dev/null +++ b/docs/projects/overview.md @@ -0,0 +1,38 @@ +--- +sidebar_position: 0 +title: Projects Overview +--- + +# Projects Overview + +This catalog summarises the initiatives maintained by Monynha Softwares. Each project page provides deeper product context, user journeys, and implementation notes. Use this overview to decide where to contribute or which solution best matches a customer request. + +## Portfolio at a glance + +| Project | Purpose | Status | Primary Tech | Key Links | +| --- | --- | --- | --- | --- | +| [Boteco Pro](./boteco-pro.md) | Hospitality management suite for bars and restaurants. | Beta rollout | Flutter, Convex backend | [Repository](https://github.com/Monynha-Softwares/Boteco-Pro) | +| [Boteco.pt](./boteco-pt/index.md) | Portugal-facing web presence for the Boteco platform. | Active | Next.js, TypeScript | [Repository](https://github.com/Monynha-Softwares/boteco.pt) | +| [ArtLeo Creative Spaces](./artleo-creative-spaces/index.md) | Digital platform supporting local artists with booking and promotion tools. | Discovery | Next.js, TypeScript | [Repository](https://github.com/Monynha-Softwares/artleo-creative-spaces) | +| [FACODI](./facodi/index.md) | Community digital college learning environment. | Active | Django, Python | [Repository](https://github.com/Monynha-Softwares/facodi.pt) | +| [Monynha.com](./monynha-com/index.md) | Corporate website highlighting services and case studies. | Live | Next.js, TypeScript | [Repository](https://github.com/Monynha-Softwares/Monynha-com) | +| [Monynha Online](./monynha-online/index.md) | Default landing experience for microsites and campaigns. | Maintenance | Next.js, TypeScript | [Repository](https://github.com/Monynha-Softwares/MonynhaOnline-Default-Page) | +| [Monynha Tech](./monynha-tech/index.md) | Knowledge base and tooling portal for partners and devs. | Active | Next.js, TypeScript | [Repository](https://github.com/Monynha-Softwares/MonynhaTech) | +| [Sweet Price](./sweet-price/index.md) | Retail price comparison app for the Portuguese market. | Alpha | React Native, Node.js | [Repository](https://github.com/Monynha-Softwares/Sweet-Price) | + +## How to propose a new project + +1. Validate the business opportunity with the product team and document the target personas. +2. Create a discovery issue in the relevant repository describing scope, success metrics, and constraints. +3. Draft an architecture canvas covering tech stack, integrations, deployment strategy, and compliance considerations. +4. Prepare a delivery roadmap with milestones, resourcing needs, and QA checkpoints. +5. Submit the documentation updates (including a new project page) through a pull request following the contribution guide. + +## Keeping project pages up to date + +- Update the status, roadmap, and release notes after every milestone. +- Link to design files, tracking dashboards, or public demos as they become available. +- Record known risks or open questions so new contributors can provide support quickly. +- Archive deprecated projects in an `/archive` folder with a clear rationale and sunset plan. + +If a project is missing or outdated, please open an issue in the `MonaDocs` repository with the details you have. diff --git a/docs/projects/sweet-price/index.md b/docs/projects/sweet-price/index.md index f69b400..5b829a9 100644 --- a/docs/projects/sweet-price/index.md +++ b/docs/projects/sweet-price/index.md @@ -1,18 +1,47 @@ # Sweet Price -## Description +## Overview -Supermarket price comparison app in Portugal. Currently supports: Pingo Doce and Continente supermarkets. +Sweet Price is a mobile and web application that helps shoppers in Portugal compare supermarket prices in real time. The product targets budget-conscious households and small businesses that need to optimise purchases across multiple retailers. -## Technologies +## Problem statement -- (TBD) +- Supermarket prices vary significantly between regions and loyalty programs. +- Shoppers lack transparent insights into promotions, bundles, and substitutions. +- Manual price tracking is time consuming and quickly outdated. -## Repository +## Product capabilities -[GitHub: Sweet-Price](https://github.com/Monynha-Softwares/Sweet-Price) +1. **Price comparison engine** – Aggregates offers from Pingo Doce, Continente, and other retailers via public APIs and scraping pipelines. +2. **Shopping lists** – Users create lists, set budgets, and receive store-specific totals. +3. **Alerts** – Notify shoppers when favourite items drop below threshold prices. +4. **Insights dashboard** – Visualise savings, seasonal trends, and substitution recommendations. -## Features +## Technology stack -- Price comparison for Portuguese supermarkets -- Support for Pingo Doce and Continente +- **Mobile**: React Native app targeting iOS and Android, sharing UI components with the web client. +- **Web**: Next.js frontend for desktop users and admin tooling. +- **Backend**: Node.js + Convex for realtime data sync and background jobs. +- **Data ingestion**: Scheduled scrapers running on GitHub Actions with fallback manual upload scripts. +- **Storage**: PostgreSQL for transactional data, Redis for caching, Supabase storage for media. + +## Data governance + +- Respect retailer terms of service; review legal guidance before adding new data sources. +- Store only aggregated price data—avoid personal information beyond hashed user IDs. +- Anonymise analytics and comply with GDPR consent requirements for tracking. + +## Roadmap + +| Initiative | Description | Status | +| --- | --- | --- | +| Loyalty program integration | Import Pingo Doce & Continente loyalty card data for personalised pricing. | Development | +| Receipt scanner | OCR-based feature to ingest receipts and enrich price database. | Discovery | +| Meal planning | Suggest weekly menus aligned with user budgets and preferences. | Planned | + +## Contribution guidelines + +- Keep scraping scripts idempotent and resilient to layout changes; add unit tests for parsers. +- Provide PT and EN copy for notifications and UI labels. +- Share performance benchmarks when touching the comparison algorithms. +- Document any new environment variables in `.env.example` and update infrastructure diagrams if relevant. diff --git a/docs/repositories/index.md b/docs/repositories/index.md index 4691a1e..5c372b4 100644 --- a/docs/repositories/index.md +++ b/docs/repositories/index.md @@ -1,12 +1,24 @@ --- id: repositories-legacy slug: /docs/repositories/legacy -title: Repositories (legacy) +title: Repositories (Legacy) sidebar_position: 999 --- # Repositories (legacy) -This legacy file has been replaced by a better client-side MDX page. See the primary page: [Repositories](/docs/repositories). +> **Status**: Archived. Use the [interactive repositories page](/docs/repositories) for the live experience. -If you are a maintainer and want to remove the legacy file, you can delete `docs/repositories/index.md` after confirming the new page works. +This file existed to avoid breaking links while the repositories page was migrated to an interactive MDX implementation. The modern page renders data client-side, supports filtering, and caches results from the GitHub API. + +### When to keep this page + +- You need a static fallback when scripting or PDF generation cannot execute client-side code. +- External partners still rely on the old `/docs/repositories/legacy` URL and cannot update immediately. + +### When to remove it + +- All known references to the legacy slug have been updated. +- Analytics show no hits for `/docs/repositories/legacy` in the past 90 days. + +If you decide to delete this page, announce it in the release notes and update redirect rules accordingly. diff --git a/docs/repositories/index.mdx b/docs/repositories/index.mdx index 960d613..104dd06 100644 --- a/docs/repositories/index.mdx +++ b/docs/repositories/index.mdx @@ -4,37 +4,65 @@ sidebar_position: 8 --- import Repositories from '@site/src/components/Repositories'; - import React from 'react'; # Repositories -This page lists repositories discovered from the GitHub user `marcelo-m7` and the organization `Monynha-Softwares`. The fetching is done entirely in the browser using the public GitHub REST API. +This page lists repositories published by the GitHub user `marcelo-m7` and the organisation `Monynha-Softwares`. The data is fetched client-side so it always reflects the latest public information. + +## Filters and URL parameters -The page accepts optional query parameters in the URL: +You can control the dataset through query parameters: -- `mode`: `user` (show only user repos), `org` (show only organization repos), or `both` (default) -- `showForks`: `1` or `true` to include forked repos +- `mode`: `user`, `org`, or `both` (default) to choose which GitHub accounts to load. +- `showForks`: `1`/`true` to include forks alongside source repositories. Examples: -- `/docs/repositories?mode=user` — show only `marcelo-m7` repos -- `/docs/repositories?mode=org&showForks=1` — show only `Monynha-Softwares` repos including forks +- `/docs/repositories?mode=user` — list only `marcelo-m7` repositories. +- `/docs/repositories?mode=org&showForks=1` — show organisational repositories including forks. + +## Authentication and rate limits + +The component uses the public GitHub REST API. Anonymous requests are limited to 60 per hour. When iterating on this page locally you can raise the limit by creating a [fine-grained personal access token](https://github.com/settings/tokens) and providing it at runtime: + +```bash +GITHUB_TOKEN=ghp_yourtoken npm run start +``` + +The token is read from `process.env.GITHUB_TOKEN` and never persisted in the browser. Do **not** commit secrets—document them in `.env.example` if new variables are required. + +## Caching strategy + +- Responses are cached in `localStorage` for six hours to reduce API calls. +- Cache keys include the selected `mode` and `showForks` values to avoid stale mixes. +- Use the “force refresh” button in the component (or clear local storage manually) after making repository changes that must appear immediately. + +## Accessibility considerations + +- All interactive controls meet WCAG AA contrast ratios and are reachable via keyboard. +- Loading states announce progress through `aria-live` regions. +- Repository cards expose headings, descriptions, and primary language details for screen-reader navigation. export function RepositoryPageWrapper() { - const params = typeof window !== 'undefined' ? new URLSearchParams(window.location.search) : new URLSearchParams(''); - const mode = params.get('mode') || 'both'; - const showForks = params.get('showForks') === '1' || params.get('showForks') === 'true'; - let user = 'marcelo-m7'; - let org = 'Monynha-Softwares'; - if (mode === 'org') user = null; - if (mode === 'user') org = null; - return ; + const params = typeof window !== 'undefined' ? new URLSearchParams(window.location.search) : new URLSearchParams(''); + const mode = params.get('mode') || 'both'; + const showForks = params.get('showForks') === '1' || params.get('showForks') === 'true'; + + let user = 'marcelo-m7'; + let org = 'Monynha-Softwares'; + if (mode === 'org') user = null; + if (mode === 'user') org = null; + + return ; } -Notes: +## Troubleshooting + +- If GitHub rate limits are reached, authenticate with a token or wait for the hourly window to reset. +- Check browser console logs for API errors; the component surfaces detailed messages for 4xx/5xx responses. +- When repositories are missing, confirm they are public and not archived. -- Data is cached in `localStorage` for 6 hours to reduce requests and avoid hitting anonymous API rate limits. -- If you need higher rate limits, provide a GitHub personal access token, but do not embed secrets in client-side code. +For the legacy static list, see the [archived page](./index.md). diff --git a/sidebars.js b/sidebars.js index 37d1a18..ecace29 100644 --- a/sidebars.js +++ b/sidebars.js @@ -102,7 +102,7 @@ const TOP_FOLDERS = [ ]; /** @type {any[]} */ -const tutorialSidebar = ['intro']; +const tutorialSidebar = ['intro', 'content-audit-2025-11']; for (const folder of TOP_FOLDERS) { const items = listDocsInDir(folder);