From df9311c22cb2e28f26d811020e829ad57091a5c2 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 14 Jul 2025 18:55:03 +0000 Subject: [PATCH 1/3] docs: Completely revamp README with comprehensive project details and roadmap Co-authored-by: pavanello.emanuele --- README.md | 351 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 275 insertions(+), 76 deletions(-) diff --git a/README.md b/README.md index a60d911..6849649 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,275 @@ -# Auto Social - -A social media management tool to create, schedule, and publish content. - -## Core Features - -- **Authentication:** Email/password and OAuth for social platforms. -- **Platform Management:** Connect and manage multiple social media accounts. -- **AI-Powered Content Creation:** Generate and improve posts with AI assistance. -- **Scheduling:** Plan and schedule posts using a calendar view. -- **History & Context:** Maintain a timeline of past posts to inform AI tone and style. - -## Getting Started - -1. **Clone the repository and install dependencies:** - ```bash - git clone - cd better-plan - pnpm install - ``` - -2. **Create your environment file:** - - Create a file named `.env` in the root of the project and add the following variables. - - ```env - # Database connection - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres - POSTGRES_DB=better-plan - - # Public URL of your application - APP_URL=http://localhost:3000 - - # Secret key for signing authentication tokens - BETTER_AUTH_SECRET= - - # X/Twitter API credentials (optional) - # X_CLIENT_ID= - ``` - -3. **Start the development database:** - ```bash - pnpm db:up - ``` - -4. **Run the application:** - ```bash - pnpm dev - ``` - -## Deployment - -This application is containerized for production deployment using Docker. - -1. **Build the application image:** - ```bash - pnpm docker:build - ``` -2. **Start the services in the background:** - ```bash - pnpm docker:up - ``` - -## Available Scripts - -- `pnpm dev`: Start the development server. -- `pnpm build`: Build the application for production. -- `pnpm start`: Start the production server. -- `pnpm lint`: Lint and format the codebase. -- `pnpm db:up`: Start the development database container. -- `pnpm db:down`: Stop the development database container. -- `pnpm db:generate`: Generate database migrations. -- `pnpm docker:build`: Build the production Docker image. -- `pnpm docker:up`: Start production containers. -- `pnpm docker:down`: Stop production containers. +# Better Plan + +A modern, AI-powered social media management tool that helps you create, schedule, and publish engaging content across multiple platforms. + +## 🚀 Features + +### Core Functionality +- **🔐 Authentication & Authorization** - Secure email/password and OAuth authentication +- **📱 Multi-Platform Support** - Connect and manage multiple social media accounts (Twitter/X, with more platforms coming) +- **🤖 AI-Powered Content Creation** - Generate and improve posts with OpenAI integration +- **📅 Smart Scheduling** - Plan and schedule posts using an intuitive calendar interface +- **📊 Content History & Analytics** - Track your publishing history and maintain context for AI suggestions +- **🎨 Modern UI** - Clean, responsive interface built with Tailwind CSS and shadcn/ui components + +### AI Features +- **Context-Aware Generation** - AI learns from your writing style and post history +- **Content Improvement** - Enhance existing posts with AI suggestions +- **Flexible Deployment** - Self-hosted (free) or SaaS (subscription-based) AI usage +- **Smart Suggestions** - Get AI-powered content ideas based on your niche and audience + +### Developer Experience +- **Type-Safe** - Built with TypeScript for better development experience +- **Modern Stack** - React 19, TanStack Start, Drizzle ORM, and Vite +- **Containerized** - Docker support for easy deployment +- **Database Migration** - Automatic schema management with Drizzle Kit + +## 🛠️ Tech Stack + +- **Frontend**: React 19, TanStack Start, TanStack Query, Tailwind CSS +- **Backend**: TanStack Start (full-stack), Better Auth +- **Database**: PostgreSQL with Drizzle ORM +- **AI**: OpenAI GPT integration +- **Build Tools**: Vite, TypeScript, Biome (linting) +- **Deployment**: Docker, GitHub Actions CI/CD + +## 🚦 Getting Started + +### Prerequisites +- Node.js 18+ and pnpm +- PostgreSQL database +- OpenAI API key (optional, for AI features) + +### Installation + +1. **Clone the repository** + ```bash + git clone https://github.com/your-username/better-plan.git + cd better-plan + ``` + +2. **Install dependencies** + ```bash + pnpm install + ``` + +3. **Set up environment variables** + + Create a `.env` file in the root directory: + ```env + # Database + POSTGRES_USER=postgres + POSTGRES_PASSWORD=postgres + POSTGRES_DB=better-plan + + # App Configuration + APP_URL=http://localhost:3000 + BETTER_AUTH_SECRET=your-secret-key-here + + # AI Features (Optional) + OPENAI_API_KEY=sk-your-openai-key-here + DEPLOYMENT_TYPE=self-hosted + AI_MODEL=gpt-4o-mini + + # Social Media APIs (Optional) + X_CLIENT_ID=your-twitter-client-id + X_CLIENT_SECRET=your-twitter-client-secret + ``` + +4. **Start the development database** + ```bash + pnpm run dev:docker + ``` + +5. **Run database migrations** + ```bash + pnpm run db:migrate + ``` + +6. **Start the development server** + ```bash + pnpm dev + ``` + +Visit `http://localhost:3000` to access the application. + +## 🎯 Usage + +### Setting Up Social Media Accounts + +1. **Sign up/Login** - Create an account or sign in with your credentials +2. **Connect Platforms** - Go to the Platforms page and connect your social media accounts +3. **Authorize Access** - Complete the OAuth flow for each platform you want to use + +### Creating and Publishing Content + +1. **Create Post** - Use the post editor to write your content +2. **AI Assistance** - Click "Suggest" for AI-generated drafts or "Improve" to enhance existing content +3. **Schedule or Publish** - Choose to publish immediately or schedule for later +4. **Track History** - View your published posts and their performance + +### AI Features Setup + +For self-hosted installations: +- Set `DEPLOYMENT_TYPE=self-hosted` in your `.env` file +- Configure your `OPENAI_API_KEY` +- Enjoy unlimited AI features + +For SaaS deployments: +- Set `DEPLOYMENT_TYPE=saas` +- Configure subscription limits +- See [AI Features Setup Guide](./setup-ai.md) for detailed instructions + +## 📚 Documentation + +- [AI Features Setup Guide](./setup-ai.md) - Comprehensive guide for configuring AI features +- [Release Management](./docs/RELEASE.md) - How to create releases and deploy +- [AI Features Roadmap](./docs/ai-features-roadmap.md) - Planned AI enhancements +- [MVP Scope](./docs/mvp.md) - Current MVP features and goals + +## 🤝 Contributing + +We welcome contributions! Here's how to get started: + +### Development Setup + +1. **Fork the repository** and clone your fork +2. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` +3. **Make your changes** following our coding standards +4. **Test your changes** + ```bash + pnpm lint + pnpm check-types + pnpm build + ``` +5. **Commit with conventional commits** + ```bash + git commit -m "feat: add new scheduling feature" + ``` +6. **Push and create a pull request** + +### Commit Message Format + +We use [Conventional Commits](https://www.conventionalcommits.org/) for automated versioning: + +- `feat:` - New features (minor version bump) +- `fix:` - Bug fixes (patch version bump) +- `docs:` - Documentation changes +- `style:` - Code style changes +- `refactor:` - Code refactoring +- `test:` - Adding tests +- `feat!:` or `BREAKING CHANGE:` - Breaking changes (major version bump) + +### Code Standards + +- **TypeScript** - All code must be properly typed +- **Biome** - We use Biome for linting and formatting +- **Components** - Use shadcn/ui components when possible +- **Database** - Use Drizzle ORM for all database operations +- **Authentication** - Use Better Auth for all auth-related features + +### Available Scripts + +```bash +# Development +pnpm dev # Start development server +pnpm dev:docker # Start development with Docker +pnpm db:studio # Open Drizzle Studio + +# Building & Testing +pnpm build # Build for production +pnpm lint # Run linting +pnpm lint:fix # Fix linting issues +pnpm check-types # Type checking + +# Database +pnpm db:generate # Generate migrations +pnpm db:migrate # Run migrations +pnpm db:studio # Database management UI + +# Docker +pnpm docker:build # Build production image +pnpm docker:up # Start production containers +pnpm docker:down # Stop containers + +# Release +pnpm release:patch # Patch version release +pnpm release:minor # Minor version release +pnpm release:major # Major version release +``` + +## 🚀 Deployment + +### Docker Deployment + +1. **Build the image** + ```bash + pnpm docker:build + ``` + +2. **Start the services** + ```bash + pnpm docker:up + ``` + +### Manual Deployment + +1. **Build the application** + ```bash + pnpm build + ``` + +2. **Start the production server** + ```bash + pnpm start + ``` + +### Automated Deployment + +We use GitHub Actions for CI/CD: +- **Docker images** are automatically built and pushed to GitHub Container Registry +- **Releases** are created automatically based on conventional commits +- **Multi-platform support** (amd64, arm64) for Docker images + +## 📈 Roadmap + +### Current MVP Features +- ✅ User authentication and authorization +- ✅ Twitter/X integration +- ✅ Basic content creation and scheduling +- ✅ AI-powered content generation +- ✅ Post history and timeline + +### Upcoming Features +- 🔄 Additional social media platforms (LinkedIn, Instagram, Facebook) +- 🔄 Advanced AI features (competitor analysis, bulk content planning) +- 🔄 Team collaboration and approval workflows +- 🔄 Advanced analytics and performance tracking +- 🔄 Content templates and reusable formats + +See our [AI Features Roadmap](./docs/ai-features-roadmap.md) for detailed planned enhancements. + +## 📄 License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +## 🆘 Support + +- **Issues** - Report bugs or request features via [GitHub Issues](https://github.com/your-username/better-plan/issues) +- **Discussions** - Join community discussions for questions and ideas +- **Documentation** - Check the `docs/` directory for detailed guides + +## 🙏 Acknowledgments + +- Built with [TanStack Start](https://tanstack.com/start) for the full-stack framework +- UI components from [shadcn/ui](https://ui.shadcn.com/) +- Authentication via [Better Auth](https://www.better-auth.com/) +- Database management with [Drizzle ORM](https://orm.drizzle.team/) +- AI integration powered by [OpenAI](https://openai.com/) + +--- + +**Better Plan** - Making social media management better, one post at a time. 🚀 From be8ad844d9f4a34f470b399418b1b8de272c29be Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 14 Jul 2025 19:00:21 +0000 Subject: [PATCH 2/3] Switch to SQLite/Turso for flexible, scalable database support Co-authored-by: pavanello.emanuele --- README.md | 32 ++++++++++++++++++++------------ docs/context.md | 2 +- 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 6849649..6e41743 100644 --- a/README.md +++ b/README.md @@ -23,12 +23,13 @@ A modern, AI-powered social media management tool that helps you create, schedul - **Modern Stack** - React 19, TanStack Start, Drizzle ORM, and Vite - **Containerized** - Docker support for easy deployment - **Database Migration** - Automatic schema management with Drizzle Kit +- **Flexible Database** - SQLite for local development, Turso for production scaling ## 🛠️ Tech Stack - **Frontend**: React 19, TanStack Start, TanStack Query, Tailwind CSS - **Backend**: TanStack Start (full-stack), Better Auth -- **Database**: PostgreSQL with Drizzle ORM +- **Database**: SQLite (local development) / Turso (production/SaaS) with Drizzle ORM - Edge-ready, serverless-friendly - **AI**: OpenAI GPT integration - **Build Tools**: Vite, TypeScript, Biome (linting) - **Deployment**: Docker, GitHub Actions CI/CD @@ -37,8 +38,8 @@ A modern, AI-powered social media management tool that helps you create, schedul ### Prerequisites - Node.js 18+ and pnpm -- PostgreSQL database - OpenAI API key (optional, for AI features) +- Turso account (optional, for production/SaaS deployment) ### Installation @@ -57,10 +58,10 @@ A modern, AI-powered social media management tool that helps you create, schedul Create a `.env` file in the root directory: ```env - # Database - POSTGRES_USER=postgres - POSTGRES_PASSWORD=postgres - POSTGRES_DB=better-plan + # Database (SQLite for development, Turso for production) + DATABASE_URL=file:///app/data/local.db + DATABASE_AUTH_TOKEN= + DATABASE_DIALECT=sqlite # App Configuration APP_URL=http://localhost:3000 @@ -75,22 +76,29 @@ A modern, AI-powered social media management tool that helps you create, schedul X_CLIENT_ID=your-twitter-client-id X_CLIENT_SECRET=your-twitter-client-secret ``` - -4. **Start the development database** - ```bash - pnpm run dev:docker + + **For production/SaaS with Turso:** + ```env + DATABASE_URL=libsql://your-database-url.turso.io + DATABASE_AUTH_TOKEN=your-turso-auth-token + DATABASE_DIALECT=turso ``` -5. **Run database migrations** +4. **Run database migrations** ```bash pnpm run db:migrate ``` -6. **Start the development server** +5. **Start the development server** ```bash pnpm dev ``` + **Optional: Start with Docker (includes database)** + ```bash + pnpm run dev:docker + ``` + Visit `http://localhost:3000` to access the application. ## 🎯 Usage diff --git a/docs/context.md b/docs/context.md index f573b38..ea19459 100644 --- a/docs/context.md +++ b/docs/context.md @@ -3,7 +3,7 @@ ### 1. Goal & Tech Stack - **Objective**: MVP of a social media management tool to connect accounts, create, and schedule posts. - **Initial Platform**: X (Twitter). -- **Tech Stack**: TanStack Start, Drizzle ORM (PostgreSQL), Tailwind CSS, Shadcn/ui, and `better-auth` for user authentication. +- **Tech Stack**: TanStack Start, Drizzle ORM (SQLite/Turso), Tailwind CSS, Shadcn/ui, and `better-auth` for user authentication. ### 2. Backend & Database Structure - **Schema**: A Drizzle schema is defined in `integrations-schema.ts` for an `integrations` table. It's designed to store multiple platform credentials per user. For X, the `accessToken` column stores the OAuth 1.0a `accessToken` and `accessSecret` concatenated with a colon (e.g., `"token:secret"`). From c67cc31ee080cf263cfaafb0b42ef86f8c124d5a Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Mon, 14 Jul 2025 19:02:13 +0000 Subject: [PATCH 3/3] docs: Update README with Docker, CI/CD, and deployment details Co-authored-by: pavanello.emanuele --- README.md | 127 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 118 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 6e41743..ad83656 100644 --- a/README.md +++ b/README.md @@ -45,7 +45,7 @@ A modern, AI-powered social media management tool that helps you create, schedul 1. **Clone the repository** ```bash - git clone https://github.com/your-username/better-plan.git + git clone https://github.com/epavanello/better-plan.git cd better-plan ``` @@ -179,6 +179,14 @@ We use [Conventional Commits](https://www.conventionalcommits.org/) for automate - **Database** - Use Drizzle ORM for all database operations - **Authentication** - Use Better Auth for all auth-related features +### Docker & CI/CD Development + +- **Docker builds** are automatically triggered on push to main/develop branches +- **Multi-platform support** - All images support amd64 and arm64 architectures +- **GitHub Container Registry** - Images are published to `ghcr.io/epavanello/better-plan` +- **Security attestations** - All images include build provenance and attestations +- **Local testing** - Use `pnpm docker:build` to test Docker builds locally + ### Available Scripts ```bash @@ -202,6 +210,8 @@ pnpm db:studio # Database management UI pnpm docker:build # Build production image pnpm docker:up # Start production containers pnpm docker:down # Stop containers +pnpm dev:docker # Start development with Docker +pnpm dev:docker:down # Stop development containers # Release pnpm release:patch # Patch version release @@ -211,9 +221,52 @@ pnpm release:major # Major version release ## 🚀 Deployment -### Docker Deployment +### Using Pre-built Docker Images + +The easiest way to deploy Better Plan is using our pre-built Docker images from GitHub Container Registry. + +#### Available Images + +All images are available at `ghcr.io/epavanello/better-plan` with the following tags: + +- **`latest`** - Latest stable release from main branch +- **`develop`** - Latest development build +- **`v1.2.3`** - Specific version tags +- **`1.2`** - Major.minor tags +- **`1`** - Major version tags + +#### Quick Start with Docker + +```bash +# Pull and run the latest version +docker run -p 3000:3000 \ + -e DATABASE_URL="file:///app/data/local.db" \ + -e DATABASE_DIALECT="sqlite" \ + -e BETTER_AUTH_SECRET="your-secret-key" \ + -e APP_URL="http://localhost:3000" \ + ghcr.io/epavanello/better-plan:latest + +# Or use docker-compose +curl -O https://raw.githubusercontent.com/epavanello/better-plan/main/docker-compose.yaml +docker-compose up -d +``` + +#### Production Deployment with Turso + +```bash +docker run -p 3000:3000 \ + -e DATABASE_URL="libsql://your-database.turso.io" \ + -e DATABASE_AUTH_TOKEN="your-turso-token" \ + -e DATABASE_DIALECT="turso" \ + -e BETTER_AUTH_SECRET="your-secret-key" \ + -e APP_URL="https://your-domain.com" \ + -e OPENAI_API_KEY="sk-your-openai-key" \ + ghcr.io/epavanello/better-plan:latest +``` + +### Local Docker Development -1. **Build the image** +1. **Build the image locally** ```bash pnpm docker:build ``` @@ -223,6 +276,11 @@ pnpm release:major # Major version release pnpm docker:up ``` +3. **Stop the services** + ```bash + pnpm docker:down + ``` + ### Manual Deployment 1. **Build the application** @@ -235,12 +293,62 @@ pnpm release:major # Major version release pnpm start ``` -### Automated Deployment +### Automated CI/CD + +Our GitHub Actions workflows automatically handle: -We use GitHub Actions for CI/CD: -- **Docker images** are automatically built and pushed to GitHub Container Registry -- **Releases** are created automatically based on conventional commits -- **Multi-platform support** (amd64, arm64) for Docker images +#### Docker Workflow (`.github/workflows/docker.yml`) +- **Triggers**: Push to `main`/`develop`, pull requests, releases, manual trigger +- **Multi-platform builds**: linux/amd64, linux/arm64 +- **Registry**: GitHub Container Registry (`ghcr.io`) +- **Caching**: GitHub Actions cache for faster builds +- **Security**: Build attestations and provenance tracking + +#### Release Workflow (`.github/workflows/release.yml`) +- **Automatic versioning**: Based on conventional commits +- **Changelog generation**: From commit messages +- **Version bumping**: Patch, minor, or major releases +- **Release creation**: Automated GitHub releases +- **Docker trigger**: Automatically builds Docker images for releases + +#### Tagging Strategy + +```bash +# For release v1.2.3, these tags are created: +ghcr.io/epavanello/better-plan:v1.2.3 # Exact version +ghcr.io/epavanello/better-plan:1.2 # Major.minor +ghcr.io/epavanello/better-plan:1 # Major version +ghcr.io/epavanello/better-plan:latest # Latest stable (main branch) + +# For development: +ghcr.io/epavanello/better-plan:develop # Development branch +ghcr.io/epavanello/better-plan:pr-123 # Pull request builds +``` + +### Platform Support + +All Docker images support multiple architectures: +- **linux/amd64** - Standard x86_64 servers +- **linux/arm64** - ARM-based servers (Apple Silicon, AWS Graviton, etc.) + +### Environment Variables for Docker + +```bash +# Required +DATABASE_URL=file:///app/data/local.db # SQLite path or Turso URL +DATABASE_DIALECT=sqlite # sqlite or turso +BETTER_AUTH_SECRET=your-secret-key # Authentication secret +APP_URL=http://localhost:3000 # Public URL + +# Optional (AI Features) +OPENAI_API_KEY=sk-your-key # OpenAI API key +DEPLOYMENT_TYPE=self-hosted # self-hosted or saas +AI_MODEL=gpt-4o-mini # OpenAI model + +# Optional (Social Media) +X_CLIENT_ID=your-twitter-id # Twitter/X client ID +X_CLIENT_SECRET=your-twitter-secret # Twitter/X client secret +``` ## 📈 Roadmap @@ -266,9 +374,10 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file ## 🆘 Support -- **Issues** - Report bugs or request features via [GitHub Issues](https://github.com/your-username/better-plan/issues) +- **Issues** - Report bugs or request features via [GitHub Issues](https://github.com/epavanello/better-plan/issues) - **Discussions** - Join community discussions for questions and ideas - **Documentation** - Check the `docs/` directory for detailed guides +- **Docker Images** - Pre-built images available at [ghcr.io/epavanello/better-plan](https://github.com/epavanello/better-plan/pkgs/container/better-plan) ## 🙏 Acknowledgments