Update project docs and problem notes

2026-04-29 09:38:47 -04:00
parent d371c3c602
commit e319a5d092
13 changed files with 1507 additions and 53 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,94 @@
+# MD Hub Secure - Documentation Index
+
+## Project Planning
+
+| Document | Description |
+|----------|-------------|
+| [project-plan.md](project-plan.md) | Master project plan with milestones, timelines, and acceptance criteria |
+| [architecture-overview.md](architecture-overview.md) | System architecture, component diagrams, and data flow |
+
+## Architecture Decision Records (ADRs)
+
+| Document | Decision |
+|----------|----------|
+| [ADR-001: Tech Stack](adrs/adr-001-tech-stack.md) | Go backend + Preact frontend |
+| [ADR-002: Sync Protocol](adrs/adr-002-sync-protocol.md) | SimpleSync content-addressed protocol |
+| [ADR-003: SSR Strategy](adrs/adr-003-ssr-strategy.md) | Go templates with Preact hydration |
+| [ADR-004: Auth Strategy](adrs/adr-004-auth-strategy.md) | Passkeys primary, passwords fallback |
+| [ADR-005: Storage Strategy](adrs/adr-005-storage-strategy.md) | libsql + content-addressed filesystem |
+| [ADR-006: Email Strategy](adrs/adr-006-email-strategy.md) | Postmark gateway, plain-text only |
+| [ADR-007: Security Model](adrs/adr-007-security-model.md) | Defense in depth, minimal dependencies |
+
+## Milestones
+
+| Document | Duration | Focus |
+|----------|----------|-------|
+| [Milestone 1: Foundation](milestones/milestone-01-foundation.md) | Weeks 1-2 | Server, database, markdown rendering |
+| [Milestone 2: Sync Protocol](milestones/milestone-02-sync-protocol.md) | Weeks 3-4 | File sync, offline support, WebSocket |
+| [Milestone 3: Authentication](milestones/milestone-03-authentication.md) | Weeks 5-6 | Passkeys, sessions, RBAC |
+| [Milestone 4: Collaboration](milestones/milestone-04-collaboration.md) | Weeks 7-8 | Comments, email, conflict resolution |
+| [Milestone 5: Search & UI](milestones/milestone-05-search-ui.md) | Weeks 9-10 | Full-text search, design system, responsive |
+| [Milestone 6: Production](milestones/milestone-06-production.md) | Weeks 11-12 | Testing, security audit, ops docs |
+
+## Technical Specifications
+
+| Document | Topic |
+|----------|-------|
+| [SimpleSync Protocol](specs/simplesync-protocol.md) | Message formats, state machine, security |
+| [Security Specification](specs/security-specification.md) | Threat model, controls, implementation |
+| [Deployment Guide](specs/deployment-guide.md) | Docker setup, configuration, operations |
+
+## Key Metrics
+
+- **Timeline**: 12 weeks (3 months)
+- **Test Coverage Target**: >80%
+- **Performance Targets**:
+  - Initial page load: <100ms
+  - Search query: <50ms
+  - File sync: <5s
+- **Security**: Zero critical/high vulnerabilities
+- **Dependencies**: Minimal, all pinned and audited
+
+## Next Steps
+
+1. Review all documentation
+2. Approve project plan
+3. Set up repository and CI pipeline
+4. Begin Milestone 1: Foundation
+
+## Project Structure
+
+```
+md-hub-secure/
+├── docs/
+│   ├── README.md (this file)
+│   ├── project-plan.md
+│   ├── architecture-overview.md
+│   ├── adrs/
+│   │   ├── adr-001-tech-stack.md
+│   │   ├── adr-002-sync-protocol.md
+│   │   ├── adr-003-ssr-strategy.md
+│   │   ├── adr-004-auth-strategy.md
+│   │   ├── adr-005-storage-strategy.md
+│   │   ├── adr-006-email-strategy.md
+│   │   └── adr-007-security-model.md
+│   ├── milestones/
+│   │   ├── milestone-01-foundation.md
+│   │   ├── milestone-02-sync-protocol.md
+│   │   ├── milestone-03-authentication.md
+│   │   ├── milestone-04-collaboration.md
+│   │   ├── milestone-05-search-ui.md
+│   │   └── milestone-06-production.md
+│   └── specs/
+│       ├── simplesync-protocol.md
+│       ├── security-specification.md
+│       └── deployment-guide.md
+├── apps/
+│   ├── server/          # Go application
+│   └── web/             # Preact frontend
+├── packages/
+│   └── protocol/        # Shared types
+├── docker-compose.yml
+├── Dockerfile
+└── Makefile
+```