📘 Devlog #2 — v1.4.0 + v1.4.1: Production-Grade Infrastructure Without the Weight

[flamehaven01]

Hello everyone,
this is the developer of Flamehaven FileSearch.

In Devlog #1, I explained how v1.3.1 introduced semantic search without turning the project into an ML monster.

v1.4.0 + v1.4.1 is the next evolution:
a transition from "search engine" to production-ready platform.

But here's the challenge:
How do you add enterprise-grade features
without betraying the project's core philosophy of being lightweight and self-hostable?

This devlog explains how we solved that problem.

---

🎯 The Core Question Behind v1.4.x

After v1.3.1 shipped semantic search, users started asking harder questions:

• "Can I use this in production with 10,000+ documents?"
• "How do I track API usage across teams?"
• "What about image search alongside text?"
• "Can I integrate this with our existing OAuth system?"
• "How do I maintain vector indexes at scale?"

These aren't feature requests.
They're architectural challenges.

The real question became:

How do you scale Flamehaven FileSearch to enterprise requirements
without turning it into a heavyweight, complex deployment nightmare?

---

⚖️ The Fundamental Tension

Let me be honest about the design conflict we faced:

Enterprise features typically require:

• Heavy databases (PostgreSQL, vector stores)
• Complex authentication systems (OAuth2/OIDC)
• Multimodal processing (vision models)
• Usage tracking and quotas
• High-availability patterns

But Flamehaven's core values are:

• Lightweight deployment
• Fast startup (< 3 seconds)
• Simple self-hosting
• Minimal dependencies
• Predictable resource usage

These goals directly oppose each other.

Most projects choose one or the other.
We chose both — but only by being extremely selective.

---

🧠 The Key Design Principle

Production features must be optional and composable.

This principle led to four rules:

1. SQLite must remain the default — PostgreSQL is opt-in
2. API keys are primary — OAuth2/OIDC is additive, not replacement
3. Text search is core — Multimodal is a separate endpoint
4. All new features must have feature flags — No forced upgrades

Everything in v1.4.x follows from these rules.

---

🏗️ How v1.4.0 Achieves Production Scale

1️⃣ PostgreSQL Backend (Opt-In)

The Problem:
SQLite is fast and simple, but it doesn't scale to:

• Distributed deployments
• High-concurrency writes
• Gigabyte-scale vector indexes

The Solution:
Make PostgreSQL completely optional with zero code changes:

# Default: SQLite (no change)
docker run flamehaven-filesearch:1.4.0

# Production: PostgreSQL + pgvector
docker run -e DATABASE_URL="postgresql://..." \
           -e VECTOR_STORE="pgvector" \
           flamehaven-filesearch:1.4.0

Why this works:

• Same API, same behavior
• Database backend is abstracted
• Users choose their complexity level

Trade-off we accepted:
Maintaining two storage backends is harder.
But forcing PostgreSQL on everyone would violate our core values.

---

2️⃣ HNSW Vector Indexing (pgvector)

The Problem:
Linear vector search (O(n)) breaks down at 10,000+ documents.

The Solution:
Use pgvector's HNSW (Hierarchical Navigable Small World) index:

CREATE INDEX ON documents
USING hnsw (embedding vector_cosine_ops)
WITH (m = 16, ef_construction = 64);

Why this matters:

• Search time: O(log n) instead of O(n)
• Handles 100,000+ documents efficiently
• Tunable precision vs speed trade-off

The hidden complexity:
HNSW indexes require tuning (m, ef_construction, ef_search).
We provide sane defaults but expose controls for advanced users.

What we rejected:
Switching to dedicated vector databases (Pinecone, Weaviate).
Reason: That would break self-hosting simplicity.

---

3️⃣ Multimodal Search (Text + Images)

The Problem:
Users wanted to search images alongside documents.

The Wrong Approach:
Integrate heavy vision models (CLIP, etc.) into the core.

The Right Approach:
Create a separate, optional endpoint with vision delegate pattern:

# Text search (always available)
POST /api/search
{ "query": "privacy policy", "store": "docs" }

# Multimodal search (opt-in)
POST /api/search/multimodal
{
  "query": "architecture diagrams",
  "image": "base64...",
  "store": "docs"
}

Why this works:

• Text search stays fast and lightweight
• Vision processing is isolated
• Users choose when to pay the cost

Implementation detail:
We use a vision delegate system:

• Gemini API for vision understanding (optional)
• Configurable timeouts and size limits
• Graceful degradation when unavailable

What we didn't do:
Bundle PyTorch or TensorFlow.
That would destroy cold start time.

---

4️⃣ OAuth2/OIDC Integration

The Problem:
Enterprises need SSO integration (Google, Okta, Auth0).

The Solution:
Support JWT validation alongside API keys:

# API Key (default, simple)
Authorization: Bearer sk_live_abc123...

# JWT (enterprise, SSO-integrated)
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...

Why both?

• Small deployments don't need OAuth complexity
• Enterprises get SSO without forking the code

The nuance:
OAuth2 is additive, not replacement.
API keys remain the primary auth method.

---

🔧 How v1.4.1 Adds Operational Intelligence

v1.4.0 added scale.
v1.4.1 adds observability and control.

1️⃣ Usage Tracking & Quotas

The Problem:
Production deployments need to track:

• Requests per API key
• Token consumption
• Quota enforcement

The Solution:
Lightweight SQLite-based usage tracker:

class UsageTracker:
    def record_usage(self, api_key_id: str, tokens: int):
        # Fast write to SQLite
        # Check quotas before request
        # Alert at 80% threshold

Why SQLite here?
Usage data is write-heavy, local, and doesn't need distribution.
Using PostgreSQL for this would be overkill.

Trade-off:
Limited to single-instance deployments.
Multi-instance requires Redis or PostgreSQL (future work).

---

2️⃣ Admin Usage APIs

The Problem:
Operators need visibility into usage patterns.

The Solution:
Four new admin endpoints:

GET /api/admin/usage/detailed
GET /api/admin/usage/quota/{key_id}
POST /api/admin/usage/quota/{key_id}
GET /api/admin/usage/alerts

Why this matters:
Operators can answer questions like:

• Which API keys are hitting limits?
• What's our peak usage time?
• Should we increase quotas?

Security consideration:
All endpoints require X-Admin-Key header.
No API key can access usage data for other keys.

---

3️⃣ pgvector Maintenance Operations

The Problem:
Vector indexes degrade over time:

• Fragmentation from updates/deletes
• Stale statistics
• Suboptimal index structure

The Solution:
Expose maintenance operations:

vector_store.reindex_hnsw()     # Rebuild index
vector_store.vacuum_analyze()   # Reclaim space
vector_store.get_index_stats()  # Performance metrics

When to run these:

• After bulk imports
• When search slows down
• During maintenance windows

What we documented:
Full tuning guide: docs/PGVECTOR_TUNING.md

---

4️⃣ Circuit Breaker Pattern

The Problem:
Database failures cascade into total system failure.

The Solution:
Circuit breaker for database connections:

CLOSED → normal operation
OPEN → fail fast, don't retry
HALF_OPEN → test recovery

Why this matters:
System degrades gracefully instead of crashing.

Trade-off we accepted:
Adds state machine complexity.
But production systems must handle transient failures.

---

🧪 Why This Required Architectural Discipline

To ship v1.4.x without breaking everything, we had to:

1. Abstraction layers — Database, auth, and storage backends are pluggable
2. Feature flags — Every new feature can be disabled
3. Backward compatibility — v1.3.1 configs still work
4. Extensive testing — Test matrix: SQLite + PostgreSQL, API keys + OAuth

This wasn't visible in the UI — but it was essential.

You can't add enterprise features
without a foundation designed to handle them.

---

📊 What This Unlocks Going Forward

Because of v1.4.x architecture, future work becomes possible:

Immediate (v1.5.x)

• Multi-instance usage tracking (Redis)
• Kubernetes Helm charts
• Distributed caching (Redis Cluster)
• WebSocket streaming for real-time results

Medium-term (v2.0)

• Pluggable vector stores (Qdrant, Milvus)
• Custom embedding models
• Full-text search engines (Elasticsearch, Typesense)
• Multi-tenancy support

Long-term (v2.x+)

• Distributed query planning
• Cross-datacenter replication
• Built-in A/B testing for ranking

All without rewriting the system again.

---

🎭 What We Explicitly Rejected

To keep this release focused, we said no to:

❌ Bundled ML models — Violates lightweight principle
❌ Forced PostgreSQL — Breaks simple deployments
❌ GraphQL API — REST is simpler and works
❌ Built-in UI framework — Admin dashboard stays minimal
❌ Microservices architecture — Monolith is appropriate here

Each "no" was harder than each "yes."

---

🧭 Why This Matters for the Project's Direction

After v1.4.1, Flamehaven FileSearch is no longer just:

"A lightweight semantic search engine"

It is becoming:

A production-ready, self-hostable search platform
that scales to enterprise requirements
without sacrificing simplicity

And it does so by being radically modular.

---

📈 Real-World Impact

Since v1.4.0 shipped, we've seen:

• Deployments handling 50,000+ documents
• Usage tracking 100,000+ requests/day
• pgvector indexes with sub-10ms search times
• OAuth2 integration with Google Workspace, Okta

These aren't benchmarks.
These are actual production deployments.

---

🔭 Devlog #3 Preview

Possible next topics:

• How we benchmark production performance
• pgvector tuning strategies (deep dive)
• Why usage tracking is SQLite, not PostgreSQL
• OAuth2 security considerations
• Preparing for v2.0 breaking changes

---

🙏 Final Thoughts

v1.4.0 + v1.4.1 was the hardest release yet.

Not because the code was hard —
but because every feature was a philosophical choice.

Do we stay lightweight?
Do we serve production users?

The answer we arrived at:

Both — but only by being disciplined about what we say yes to.

As always — feedback, questions, and criticism are welcome.
I read everything.

---

Next: Looking forward to v1.5.x and the road to v2.0.

— Flamehaven Core Team
December 28, 2025