feat: bootstrap backend MVP and architecture docs

app/models/api_client.py

@@ -0,0 +1,31 @@
+from datetime import datetime
+from uuid import uuid4
+
+from sqlalchemy import DateTime, Integer, String, Text, func
+from sqlalchemy.dialects.postgresql import JSONB, UUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from app.db.base import Base
+
+
+class ApiClient(Base):
+    __tablename__ = "api_clients"
+
+    id: Mapped[str] = mapped_column(UUID(as_uuid=False), primary_key=True, default=lambda: str(uuid4()))
+    client_key: Mapped[str] = mapped_column(Text, unique=True, nullable=False)
+    name: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="active")
+    api_key_hash: Mapped[str] = mapped_column(Text, nullable=False)
+
+    allowed_origins: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
+    allowed_ips: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
+    allowed_paths: Mapped[list[str]] = mapped_column(JSONB, nullable=False, default=list)
+
+    rate_limit_per_min: Mapped[int | None] = mapped_column(Integer)
+    expires_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    last_used_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now(), nullable=False)
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True), server_default=func.now(), onupdate=func.now(), nullable=False
+    )