# Project Hints for smarts3

## Current State (v3.0.0)

- Native custom S3 server implementation (Smarts3Server)
- No longer uses legacy s3rver backend (removed in v3.0.0)
- Core S3 operations working: PUT, GET, HEAD, DELETE for objects and buckets
- Multipart upload NOT yet implemented (critical gap for production)
- Authentication is hardcoded ('S3RVER'/'S3RVER') - not production-ready
- No CORS support yet
- No SSL/TLS support yet

## Production Readiness

See `production-readiness.md` for the complete gap analysis and implementation plan.

**Key Missing Features for Production:**
1. Multipart upload support (HIGHEST PRIORITY)
2. Configurable authentication
3. CORS middleware
4. SSL/TLS support
5. Production configuration system
6. Production logging

## Architecture Notes

### File Structure
- `ts/classes/smarts3-server.ts` - Main server class
- `ts/classes/filesystem-store.ts` - Storage layer (filesystem-backed)
- `ts/classes/router.ts` - URL routing with pattern matching
- `ts/classes/middleware-stack.ts` - Middleware execution
- `ts/classes/context.ts` - Request/response context
- `ts/classes/s3-error.ts` - S3-compatible error handling
- `ts/controllers/` - Service, bucket, and object controllers
- `ts/index.ts` - Main export (Smarts3 class)

### Storage Layout
- Objects stored as: `{bucket}/{encodedKey}._S3_object`
- Metadata stored as: `{bucket}/{encodedKey}._S3_object.metadata.json`
- MD5 stored as: `{bucket}/{encodedKey}._S3_object.md5`
- Keys are encoded for Windows compatibility (hex encoding for invalid chars)

### Current Limitations
- Max file size limited by available memory (no streaming multipart)
- Single server instance only (no clustering)
- No versioning support
- No access control beyond basic auth

## Testing

- Main test: `test/test.aws-sdk.node.ts` - Tests AWS SDK v3 compatibility
- Run with: `pnpm test`
- Tests run with cleanSlate mode enabled

## Dependencies

- `@push.rocks/smartbucket` - S3 abstraction layer
- `@push.rocks/smartfs` - Modern filesystem operations with Web Streams API (replaced smartfile)
- `@push.rocks/smartxml` - XML generation/parsing
- `@push.rocks/smartpath` - Path utilities
- `@tsclass/tsclass` - TypeScript utilities

## Migration Notes (2025-11-23)

Successfully migrated from `@push.rocks/smartfile` + native `fs` to `@push.rocks/smartfs`:
- All file/directory operations now use smartfs fluent API
- Web Streams → Node.js Streams conversion for HTTP compatibility
- All tests passing ✅
- Build successful ✅

## Next Steps

Waiting for approval to proceed with production-readiness implementation.
Priority 1 is implementing multipart uploads.