Add comprehensive documentation: architecture.md and CLAUDE.md#3
Add comprehensive documentation: architecture.md and CLAUDE.md#3
Conversation
- architecture.md: Detailed system architecture with ASCII diagrams, fork additions, storage architecture, database schema, and reference configuration - CLAUDE.md: Development guidelines, quick reference, fork context, and common tasks for maintainers and contributors Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
WalkthroughThis PR introduces two comprehensive documentation files for the Maddy Mail Server fork. CLAUDE.md provides developer guidance on building, testing, and extending REST API endpoints with schema and testing examples, while architecture.md details the REST API design, mailbox provisioning workflows, storage architecture, DNS provider integration, and production configuration patterns. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~20 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
architecture.md (4)
13-41: Add language specifiers to ASCII diagram code blocks.Markdown code blocks should declare a language identifier for proper syntax highlighting. ASCII diagrams can use plain text or a generic language.
♻️ Proposed fixes for code block language specifiers
Update the fenced code block markers:
-``` +```textApply this change to the ASCII diagram blocks at:
- Lines 13-41 (architecture diagram)
- Lines 85-123 (REST API middleware stack)
- Lines 191-242 (user/mailbox workflows)
- Lines 276-317 (storage architecture)
- Lines 394-415 (fork-added directories)
- Lines 419-432 (upstream directories)
Also applies to: 85-123, 191-242, 276-317, 394-415, 419-432
141-159: Add language specifier to Go code block.Line 141 declares a Go struct definition but lacks the
golanguage identifier.♻️ Proposed fix
-```go +```go // Create user with optional mailbox provisioning type CreateUserDto struct {
322-327: Add language specifier to SQL code block.Line 322 contains SQL but lacks the
sqllanguage identifier.♻️ Proposed fix
-```sql +```sql CREATE TABLE credentials ( username varchar NOT NULL PRIMARY KEY, password varchar NOT NULL -- bcrypt hash );
465-531: Add language specifier to configuration code block.Line 465 contains Maddy configuration syntax but lacks a language identifier.
♻️ Proposed fix
-``` +```conf # Base variables $(hostname) = example.orgCLAUDE.md (1)
228-234: Add language specifier to configuration code block.Line 228 contains Maddy configuration syntax but lacks a language identifier.
♻️ Proposed fix
-``` +```conf storage.imapsql local_mailboxes { sent_mailbox "Sent Messages" trash_mailbox "Deleted Items" # ... }
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting
📒 Files selected for processing (2)
CLAUDE.mdarchitecture.md
🧰 Additional context used
🪛 LanguageTool
architecture.md
[grammar] ~260-~260: Ensure spelling is correct
Context: ...er Support Added build support for AWS Route53 and Cloudflare DNS providers for ACME c...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
CLAUDE.md
228-228: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
architecture.md
13-13: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
85-85: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
191-191: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
276-276: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
334-334: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
346-346: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
364-364: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
394-394: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
419-419: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
465-465: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (8)
CLAUDE.md (5)
1-50: Approve documentation structure and cross-referencing.The document provides a clear quick-reference guide complementing architecture.md well. The cross-reference at line 3 properly directs readers to the detailed architecture documentation, and the organization facilitates both quick lookups and deep-dive learning.
164-186: Approve testing guidance and manual API examples.The manual API testing section with curl examples and integration testing guidance is practical and well-documented. The basic auth examples correctly reflect the implementation approach.
1-10: Commands in quick reference are correct and align with build.sh.The documented build commands follow the correct syntax pattern and are supported by the build.sh script. Both
./build.sh buildand./build.sh --tags 'libdns_route53' buildare valid, matching the expected./build.sh [options] {build,install}usage pattern.
141-145: The documented module names are correctly implemented in the codebase. Bothlocal_authdb(authentication configuration inutil.go:50) andlocal_mailboxes(IMAP storage inutil.go:69) are actively used in configuration handling throughout the CLI tools and tests. The descriptions match their actual implementations.
54-128: The global database variables are correctly initialized in api.go (lines 18-22) with the exact types referenced in the documentation. Verification confirms:
userDb(module.PlainUserDB) initialized at line 27 viaopenUserDB()and used in users.go handlersimapDb(module.ManageableStorage) initialized at line 34 viaopenStorage()and used in imapAccounts.go handlersmailboxes(Mailboxes) initialized at line 34 viaopenStorage()and used in imapAccounts.go for folder namesThe documentation accurately reflects the actual implementation.
architecture.md (3)
125-138: REST API endpoints in architecture.md are accurate and consistent with the actual implementation in api.go. All 9 endpoints match their implementations, auth requirements are correctly specified, and query parameters/options are documented appropriately.
1-50: All file paths and module references in the documentation are verified and accurate. All REST API handler files (api.go, users.go, imapAccounts.go, util.go), upstream component files (internal/endpoint/smtp/smtp.go, internal/endpoint/imap/imap.go, internal/msgpipeline/msgpipeline.go, internal/storage/imapsql/imapsql.go), framework modules (framework/module/auth.go, framework/module/storage.go), and REST utility infrastructure (internal/rest/model/user.go, internal/rest/util/server/server.go, internal/rest/util/server/secure.go, internal/rest/util/middleware/basic_auth/basic_auth.go) exist in the repository. Module names PlainUserDB, ManageableStorage, and pass_table match their actual code interface definitions.
319-387: Verify database schema documentation against go-imap-sql implementation.The documented schema tables (users, mboxes, msgs) and their columns should be verified against the actual go-imap-sql v0.5.1-0.20240831122236-655e4cb87d20 implementation in the
schema.goandsql.gofiles of the foxcpp/go-imap-sql repository to ensure column names, types, and constraints match.
1 participant
Summary
architecture.md: Detailed system architecture with ASCII diagrams, fork additions, REST API, storage architecture, complete database schema documentation, and reference configurationCLAUDE.md: Development guidelines, quick reference commands, fork context, development patterns, and common tasksTest Plan
🤖 Generated with Claude Code
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.