{"id":31583047,"url":"https://github.com/matthewatkins/carve-template","last_synced_at":"2026-04-10T00:47:37.994Z","repository":{"id":309647804,"uuid":"1033498782","full_name":"matthewatkins/carve-template","owner":"matthewatkins","description":"Opinionated end-to-end type safe full stack monorepo template.","archived":false,"fork":false,"pushed_at":"2025-08-13T02:26:42.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-13T04:06:40.844Z","etag":null,"topics":["bun","elysiajs","nuxtjs","tailwindcss","typescript","vuejs"],"latest_commit_sha":null,"homepage":"https://carve.atkins.codes","language":"Vue","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matthewatkins.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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}},"created_at":"2025-08-06T23:07:54.000Z","updated_at":"2025-08-13T02:26:45.000Z","dependencies_parsed_at":"2025-08-13T04:06:49.125Z","dependency_job_id":"60fc6358-992d-4702-b2c9-e51a1c2e90a4","html_url":"https://github.com/matthewatkins/carve-template","commit_stats":null,"previous_names":["matthewatkins/carve-template"],"tags_count":null,"template":true,"template_full_name":null,"purl":"pkg:github/matthewatkins/carve-template","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewatkins%2Fcarve-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewatkins%2Fcarve-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewatkins%2Fcarve-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewatkins%2Fcarve-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matthewatkins","download_url":"https://codeload.github.com/matthewatkins/carve-template/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matthewatkins%2Fcarve-template/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278537757,"owners_count":26003250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bun","elysiajs","nuxtjs","tailwindcss","typescript","vuejs"],"created_at":"2025-10-05T23:57:30.144Z","updated_at":"2025-10-05T23:57:33.309Z","avatar_url":"https://github.com/matthewatkins.png","language":"Vue","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Carve\n\nA modern TypeScript stack with microservices architecture, combining Nuxt, Elysia, ORPC, Better Auth, and more.\n\n## Features\n\n- **TypeScript** - For type safety and improved developer experience\n- **Nuxt** - The Intuitive Vue Framework\n- **TailwindCSS** - Utility-first CSS for rapid UI development\n- **Elysia** - Type safe server framework\n- **oRPC** - End-to-end type-safe APIs with OpenAPI integration\n- **Bun** - Runtime environment\n- **Drizzle** - TypeScript-first ORM\n- **PostgreSQL** - Database engine\n- **Authentication** - Email \u0026 password authentication with Better Auth\n- **Better Auth Sessions** - Service-to-service authentication\n- **Biome** - Linting and formatting\n- **Husky** - Git hooks for code quality\n- **Turborepo** - Optimized monorepo build system\n- **Changesets** - Versioning and publishing\n\n## Architecture Overview\n\nThis project uses a microservices architecture with three main services:\n\n### Services\n\n1. **Web App** (`apps/web/`) - Port 3000\n   - Frontend UI that consumes both servers\n   - Uses Better Auth client for authentication\n   - Uses shared API client for business logic\n\n2. **Auth Server** (`apps/auth-server/`) - Port 3001\n   - Handles all authentication and authorization\n   - Database: Auth-specific schema (users, sessions, accounts)\n   - Endpoints: `/api/auth/**` (login, register, session management)\n   - Validates Better Auth sessions for API server communication\n\n3. **API Server** (`apps/api-server/`) - Port 3002\n   - Handles all application logic and business data\n   - Database: Application-specific schema\n   - Endpoints: `/rpc/**` (all application endpoints)\n   - Validates Better Auth sessions from auth server\n\n### Shared Packages\n\n- **`packages/api/`** - Shared oRPC router definitions and type-safe API procedures\n- **`packages/shared-types/`** - Common TypeScript interfaces\n- **`packages/shared-utils/`** - Shared utilities (session validation, database helpers)\n\n## Quick Start\n\n### Option 1 - Automatic Setup\n#### 1. Initialize Project\n\nIf you're using this as a template, you can initialize your project using the carve script. This will handle everything for you.\n\n```bash\n# Interactive project initialization\nbun run carve\n```\n\nThis will:\n- Detect your project name from the directory\n- Update all package names and imports\n- Create a backup before making changes\n- Offer package installs\n- Offer docker and DB setup\n- Provide clear next steps\n\n### Option 2 - Manual Setup\n#### 1. Install Dependencies\n```bash\nbun install\n```\n\n### 2. Set Up Database with Docker\n\n#### Start PostgreSQL\n```bash\n# Start the database\ndocker-compose up --build -d\n```\n\n#### Set up environment variables\n\n**Auth Server** (create `apps/auth-server/.env`)\n```env\nAUTH_DATABASE_URL=\"postgresql://postgres:postgres@localhost:5432/auth_db\"\nBETTER_AUTH_SECRET=\"your-secret\"\nBETTER_AUTH_URL=\"http://localhost:3001\"\nCORS_ORIGIN=\"http://localhost:3000\"\n```\n\n**API Server** (create `apps/api-server/.env`)\n```env\nAPI_DATABASE_URL=\"postgresql://postgres:postgres@localhost:5432/api_db\"\nAUTH_SERVER_URL=\"http://localhost:3001\"\nCORS_ORIGIN=\"http://localhost:3000\"\n```\n\n**Web App** (create `apps/web/.env`)\n```env\nAUTH_SERVER_URL=\"http://localhost:3001\"\nAPI_SERVER_URL=\"http://localhost:3002\"\n```\n\n#### Push database schemas\n```bash\n# Push auth schema\nbun run db:push:auth\n\n# Push API schema\nbun run db:push:api\n```\n\n### 3. Start All Services\n\n#### Option A: Using turbo\n```bash\nbun dev\n```\n\n#### Option B: Start individually\n```bash\n# Terminal 1 - Auth Server\nbun dev:auth-server\n\n# Terminal 2 - API Server\nbun dev:api-server\n\n# Terminal 3 - Web App\nbun dev:web\n```\n\n## Service URLs\n\n- **Web App**: http://localhost:3000\n- **Auth Server**: http://localhost:3001\n- **API Server**: http://localhost:3002\n\n## Testing the Setup\n\n### Test Services\n```bash\n# Test Web App\ncurl http://localhost:3000/\n\n# Test Auth Server\ncurl http://localhost:3001/\n\n# Test API Server\ncurl http://localhost:3002/\n```\n\n### Test Authentication Flow\n1. Open http://localhost:3000 in your browser\n2. Try to sign up/sign in\n3. Check that the web app communicates with both servers\n\n## Database Management\n\n### Start/Stop Database\n```bash\n# Start database\ndocker-compose up --build -d\n\n# Stop database\ndocker-compose down\n\n# Reset database (removes all data)\ndocker-compose down -v \u0026\u0026 docker-compose up --build -d\n```\n\n### Schema Management\n```bash\n# Push auth schema\nbun run db:push:auth\n\n# Push API schema\nbun run db:push:api\n\n# View auth database\nbun run db:studio:auth\n\n# View API database\nbun run db:studio:api\n```\n\n## Better Auth Session Architecture\n\nThis project uses Better Auth sessions for service-to-service authentication between the auth-server and api-server.\n\n### Authentication Flow\n\n1. **User Authentication**: Web app authenticates with auth server using Better Auth\n2. **Session Validation**: API server validates Better Auth sessions with auth server\n3. **API Access**: Web app uses session cookies to access protected API endpoints\n4. **Session Verification**: API server verifies sessions with auth server\n\n### Security Benefits\n\n- **No Shared Database**: API server doesn't need direct access to auth database\n- **Session Management**: Better Auth handles session lifecycle and security\n- **Cookie-based Security**: Sessions are managed securely through HTTP cookies\n- **Microservices Security**: Proper separation between auth and business logic\n\nFor detailed information, see [ARCHITECTURE.md](./docs/ARCHITECTURE.md).\n\n## Development Workflow\n\n### Adding New API Endpoints\n1. Edit `packages/api/src/router.ts`\n2. Add your new procedures\n3. The API server will automatically pick them up\n4. The web app will have type-safe access\n\n### Adding New Auth Features\n1. Extend the auth server in `apps/auth-server/`\n2. Update the shared types as needed\n3. All clients benefit from the changes\n\n### Adding New Frontends\n1. Create new app in `apps/`\n2. Install shared packages\n3. Configure environment variables\n4. Get type-safe access to all APIs\n\n## Available Scripts\n\n- `bun dev`: Start all applications in development mode\n- `bun build`: Build all applications\n- `bun dev:web`: Start only the web application\n- `bun dev:auth-server`: Start only the auth server\n- `bun dev:api-server`: Start only the API server\n- `bun check-types`: Check TypeScript types across all apps\n- `bun db:push:auth`: Push auth schema changes to database\n- `bun db:push:api`: Push API schema changes to database\n- `bun db:studio:auth`: Open auth database studio UI\n- `bun db:studio:api`: Open API database studio UI\n- `bun check`: Run Biome formatting and linting\n\n## Troubleshooting\n\n### Common Issues\n\n#### Database Connection Issues\n- Check that PostgreSQL is running: `docker ps`\n- Verify database URLs in environment variables\n- Check database logs: `docker logs carve-2-postgres`\n\n#### CORS Issues\n- Check that `CORS_ORIGIN` is set correctly\n- Verify that web app URL matches CORS settings\n\n#### Session Issues\n- Check that auth server is running\n- Verify that API server can reach auth server\n- Check environment variables\n\n#### Type Errors\n```bash\n# Check all types\nbun run check-types\n\n# Check specific service\ncd apps/auth-server \u0026\u0026 bun run check-types\n```\n\n### Port Conflicts\nIf port 5432 is already in use:\n```bash\n# Stop existing PostgreSQL\nbrew services stop postgresql\n\n# Or change the port in docker-compose.yml\nports:\n  - \"5433:5432\"  # Use port 5433 instead\n```\n\n## Architecture Benefits\n\n1. **Separation of Concerns**: Each service has a single responsibility\n2. **Scalability**: Services can be scaled independently\n3. **Security**: Auth server can be locked down separately\n4. **Flexibility**: Easy to add new services or frontends\n5. **Type Safety**: Shared packages ensure consistency\n6. **Database Isolation**: Auth and app data are separate\n7. **Better Auth Sessions**: Secure service-to-service communication\n\n## Project Structure\n\n```\ncarve-2/\n├── apps/\n│   ├── web/              # Frontend application (Nuxt)\n│   ├── auth-server/      # Authentication service (Hono + Better Auth)\n│   └── api-server/       # Business logic service (Hono + ORPC)\n├── packages/\n│   ├── api/              # Shared API router and types\n│   ├── shared-types/     # Common TypeScript interfaces\n│   └── shared-utils/     # Shared utilities\n├── docs/\n│   ├── ARCHITECTURE.md        # System architecture documentation\n│   └── ARCHITECTURE.md   # Architecture overview\n```\n\n## Next Steps\n\n1. **Add your application schema** to `apps/api-server/src/db/schema/`\n2. **Add API endpoints** to `packages/api/src/router.ts`\n3. **Customize auth features** in `apps/auth-server/`\n4. **Add more frontends** as needed\n5. **Set up production deployment** for each service\n\n## Documentation\n\n- [System Architecture](./docs/ARCHITECTURE.md) - Detailed architecture implementation\n- [Architecture Overview](./docs/ARCHITECTURE.md) - Microservices architecture details\n\n## License\n\nThis project is free to use, clone, and share for non-commercial purposes.\nYou may not sell, modify, or use the source code for commercial projects.\nSee [LICENSE.txt](./LICENSE.txt) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewatkins%2Fcarve-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatthewatkins%2Fcarve-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatthewatkins%2Fcarve-template/lists"}