# Insertr
A content management system for client websites.

I host a few client services and static web-sites and I want to integrate content management for the client. They should be able to change the content of the site, if not the layout. I am open to hearing about existing solutions, but I am considering building my own. If I were to build my own CMS I imagine an edit-in-place experience - probably with Go on the backend and something like htmx/alpine on the front-end, although I would be open for other alternatives.

## Features / User stories
This list is not exhaustive and will be expanded as we research.

### Users
This application have to keep three types of users in mind.
- *The developer* - Creating web-sites or services for small businisses
- *The client* - The one in daily control of the content. Sign in - make changes - see outcome. A simple system for any tech-litteracy level. "Update however and whenever you will, without involving tech support."
- *The customer* - Client's customers who will view and consume the site or service.

### MVP
- [ ]  Client should sign in through a SSO (I am hosting an authentik instance that should manage users through oAuth).
- [ ] See the public-facing version of their page, but with an edit button in the top right corner of "content components". If they click the button the content will be replaced with a form coresponding to the component's content, rendered in markdown. They can edit the content and submit/save their changes. 
- [ ] This will trigger an update of the content on the server.

If I were to write a wish list it would be:
- [ ] Slapp a class on a div: <div class="insertr"> | <div insetr>, and it works.

## Research Results (Completed)

### Existing Solutions Analysis
- **TinaCMS**: Git-based with visual editing, but requires Next.js/React framework
- **Strapi**: Full headless CMS, complex setup, Node.js based  
- **Contentful**: Commercial solution, API-based, not self-hosted
- **Ghost**: Publishing-focused, not suitable for general content management
- **Conclusion**: No existing solution offers the simple "add a class and it works" approach

### Tech Stack Decision: Go + htmx/Alpine
**Rationale:**
- **Go**: Fast, single binary deployment, excellent web server performance
- **htmx**: Perfect for edit-in-place with partial page updates
- **Alpine.js**: Lightweight reactive behaviors without framework complexity
- **Architecture**: Dynamic (not static site generation) for real-time editing

### Authentication Integration
- **Authentik OAuth 2.0**: Standard flow for client authentication
- **JWT tokens**: For API authorization and session management
- **Multi-tenant**: Role-based access per site/content section

## Prototype Roadmap

### Phase 1: Frontend Proof-of-Concept
**Goal**: Demonstrate edit-in-place functionality with mock data
**Deliverables**:
- [ ] Demo business website (Acme Consulting example)
- [ ] insertr.js library with core functionality
- [ ] Three user view modes (Customer/Client/Developer)
- [ ] Mock authentication flow
- [ ] Inline editing with markdown support

### Phase 2: Backend Integration
**Goal**: Connect to Go server with real data persistence
**Deliverables**:
- [ ] Go HTTP server with REST API
- [ ] File-based content storage
- [ ] Authentik OAuth integration
- [ ] Git-based version control

### Phase 3: Production Features
**Goal**: Multi-tenant deployment ready system
**Deliverables**:
- [ ] Admin dashboard
- [ ] Content validation and security
- [ ] Deployment automation
- [ ] Documentation and examples

## User Experience Design

### The Customer (End User)
- Clean website experience with no edit interface
- Fast loading, no unnecessary JavaScript

### The Client (Content Manager)  
- Same website + subtle edit indicators (✏️ icons)
- Click to edit → inline form → save/cancel
- Markdown editing for rich content
- Immediate visual feedback

### The Developer (Integration)
```html
<!-- Simple integration -->
<script src="https://insertr.example.com/insertr.js"></script>
<div class="insertr" data-content-id="hero">
  <h1>Editable Content</h1>
</div>
```

## Next Immediate Steps
1. Create demo website mockup
2. Build core insertr.js library  
3. Implement edit-in-place UI
4. Add mock authentication flow
5. Test with multiple content types