|
| 1 | +# Hollo - Coding Guidelines for AI Assistants |
| 2 | + |
| 3 | +Hollo is a federated single-user microblogging software powered by [Fedify](https://fedify.dev/). It implements ActivityPub protocol for federation with other platforms (like Mastodon, Misskey, etc.) and provides Mastodon-compatible APIs for client integration. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +- **Technology Stack**: TypeScript, Hono.js (Web framework), Drizzle ORM, PostgreSQL |
| 8 | +- **Package Manager**: pnpm only (npm is not used) |
| 9 | +- **License**: GNU Affero General Public License v3 (AGPL-3.0) |
| 10 | +- **Structure**: Single-user microblogging platform with federation capabilities |
| 11 | +- **API**: Implements Mastodon-compatible APIs for client integration |
| 12 | + |
| 13 | +## Key Architectural Components |
| 14 | + |
| 15 | +1. **API Layer** (`src/api/`): Implements Mastodon-compatible REST APIs (v1 and v2) |
| 16 | +2. **Federation** (`src/federation/`): ActivityPub implementation for federation with other platforms |
| 17 | +3. **Database** (`src/db.ts` and `src/schema.ts`): PostgreSQL with Drizzle ORM |
| 18 | +4. **Components** (`src/components/`): React components for web interface |
| 19 | +5. **Entities** (`src/entities/`): Core domain models |
| 20 | + |
| 21 | +## Development Guidelines |
| 22 | + |
| 23 | +### Code Style |
| 24 | + |
| 25 | +1. **TypeScript**: Maintain strict typing throughout the codebase |
| 26 | +2. **Biome**: Follow Biome linting rules (configured in `biome.json`) |
| 27 | +3. **Formatting**: Use the project's established formatting patterns |
| 28 | +4. **Comments**: Add meaningful comments for complex logic, but avoid redundant documentation |
| 29 | +5. **File Organization**: Follow the established module structure |
| 30 | + |
| 31 | +### Database Guidelines |
| 32 | + |
| 33 | +1. **Migrations**: Use Drizzle migrations for database schema changes |
| 34 | +2. **Schema Design**: Follow the existing schema patterns in `src/schema.ts` |
| 35 | +3. **Relations**: Ensure proper relation definitions between tables |
| 36 | +4. **Transactions**: Properly handle database transactions for operations that require atomicity |
| 37 | + |
| 38 | +### Federation Guidelines |
| 39 | + |
| 40 | +1. **ActivityPub**: Follow ActivityPub protocol specifications |
| 41 | +2. **Compatibility**: Ensure compatibility with Mastodon and other ActivityPub implementations |
| 42 | +3. **Security**: Implement proper signature verification for federated activities |
| 43 | + |
| 44 | +### API Development |
| 45 | + |
| 46 | +1. **Mastodon Compatibility**: Maintain compatibility with Mastodon API specifications |
| 47 | +2. **Versioning**: Respect API versioning (v1 and v2) |
| 48 | +3. **Error Handling**: Use consistent error response formats |
| 49 | +4. **Authentication**: Implement proper OAuth 2.0 authentication flows |
| 50 | + |
| 51 | +### Testing |
| 52 | + |
| 53 | +1. **Coverage**: Aim for high test coverage for critical features |
| 54 | +2. **Unit Tests**: Write unit tests for business logic |
| 55 | +3. **Integration Tests**: Test API endpoints and federation functionality |
| 56 | +4. **Mocking**: Use proper mocking for external dependencies |
| 57 | +5. **Test Runner**: Use Vitest for testing (run with `pnpm test`) |
| 58 | + |
| 59 | +### Security Considerations |
| 60 | + |
| 61 | +1. **Input Validation**: Validate all user inputs using Zod or similar validation libraries |
| 62 | +2. **Authentication**: Follow secure authentication practices |
| 63 | +3. **Authorization**: Ensure proper access control for all resources |
| 64 | +4. **Data Protection**: Handle sensitive data appropriately |
| 65 | +5. **Federation Security**: Implement proper signature verification for federated activities |
| 66 | + |
| 67 | +### Performance |
| 68 | + |
| 69 | +1. **Database Queries**: Optimize database queries for performance |
| 70 | +2. **Indexing**: Use appropriate database indexes |
| 71 | +3. **Caching**: Implement caching where appropriate |
| 72 | +4. **Pagination**: Implement proper pagination for list endpoints |
| 73 | + |
| 74 | +## Development Commands |
| 75 | + |
| 76 | +- **Type Check & Lint**: `pnpm check` - Runs TypeScript type checking and linting |
| 77 | +- **Testing**: `pnpm test` - Runs automated tests using Vitest |
| 78 | +- **Formatting**: `pnpm biome format --fix` - Formats code using Biome |
| 79 | + |
| 80 | +## Important Notes |
| 81 | + |
| 82 | +1. **Single-User Focus**: Hollo is designed as a single-user platform, so multi-user logic is not needed |
| 83 | +2. **Federation**: Focus on federation capabilities is essential |
| 84 | +3. **API Compatibility**: Maintaining Mastodon API compatibility is critical for client support |
| 85 | +4. **AGPL Compliance**: Ensure all contributions comply with AGPL-3.0 license requirements |
| 86 | + |
| 87 | +When modifying code or implementing new features, always consider the federated nature of the application and ensure compatibility with other ActivityPub implementations. |
0 commit comments