Yi Fan Xia niRi Ben Yu Ban moarimasu

Live Demo: https://chatcore-ai.com/

Click a thumbnail to open the video on YouTube.

_{> Watch Demo Video}

Chat-Core is a FastAPI-based AI chat application with email-based authentication, persistent + ephemeral conversations, and prompt sharing. It integrates with Groq and Google Gemini APIs, uses PostgreSQL for storage, and ships with a Next.js frontend.

• Email-based authentication with 6-digit verification codes
• Persistent + ephemeral chat modes
• Prompt sharing with search and public visibility controls
• Groq / Gemini integrations for LLM responses

• Backend: FastAPI (Python)
• Frontend: Next.js
• Database: PostgreSQL
• Optional: Redis (for auth/session enhancements)

This project standardizes local execution on Docker Compose.

• Frontend: http://localhost:3000
• API: http://localhost:5004

For existing environments, apply incremental DB changes with Alembic:

• db/init.sql remains the bootstrap schema for brand-new databases.
• Default task definitions are centralized in frontend/data/default_tasks.json and seeded on startup.
• alembic/versions/ contains incremental migration history.
• db/performance_indexes.sql is kept as a direct SQL fallback for index-only updates.

Set these in .env or in docker-compose.yml:

• GROQ_API_KEY: Groq API key
• Gemini_API_KEY: Google Generative AI API key
• GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET: Google OAuth client credentials
• GOOGLE_PROJECT_ID: Google OAuth project ID (project_id in client config)
• GOOGLE_JS_ORIGIN: allowed JavaScript origin for Google OAuth (default: https://chatcore-ai.com)
• GROQ_MODEL: Groq model name used by OpenAI SDK (default: openai/gpt-oss-20b)
• GEMINI_DEFAULT_MODEL: default Gemini model when model is omitted (default: gemini-2.5-flash)
• LLM_DAILY_API_LIMIT: daily cap for total /api/chat LLM calls across all users (default: 300)
• AUTH_EMAIL_DAILY_SEND_LIMIT: daily cap for login/verification email sends across all users (default: 50)
• FASTAPI_SECRET_KEY: session secret (FLASK_SECRET_KEY is supported as a legacy fallback)
• ADMIN_PASSWORD_HASH: hashed admin password in format pbkdf2_sha256$iterations$salt$hash (no in-code default)
• SEND_ADDRESS / SEND_PASSWORD: Gmail account for verification emails (EMAIL_SEND_PASSWORD is accepted as a legacy fallback)
• POSTGRES_HOST / POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB: PostgreSQL settings
• DB_POOL_MIN_CONN / DB_POOL_MAX_CONN: DB connection pool min/max size (defaults: 1 / 10)
• REDIS_HOST / REDIS_PORT / REDIS_DB / REDIS_PASSWORD (optional): Redis settings
• FASTAPI_ENV: set to production to enable stricter SameSite/Secure settings (FLASK_ENV is supported as a legacy fallback)
• LOG_LEVEL (optional): app log level (default: INFO)
• LOG_DIR (optional): log output directory (default: logs)
• APP_LOG_FILE / ERROR_LOG_FILE (optional): app/error log file names (defaults: app.log / error.log)
• LOG_MAX_BYTES / LOG_BACKUP_COUNT (optional): rotating log size and retention count (defaults: 10485760 / 10)

Generate ADMIN_PASSWORD_HASH with:

• app.py: FastAPI entry point
• blueprints/: feature modules (auth, chat, memo, prompt_share, admin)
• services/: shared integrations (DB, LLM, email, user helpers)
• templates/ and static/: global HTML/CSS/JS assets
• db/init.sql: initial PostgreSQL schema
• frontend/: Next.js frontend

• Why FastAPI (instead of Flask): FastAPI gives async-first request handling, type-driven validation, and automatic OpenAPI docs. This reduces API integration friction and keeps backend contracts explicit.
  Trade-off: stricter typing and async patterns add some implementation complexity.
• Why Redis for session/state (optional): When Redis is available, sessions are stored server-side and shared across instances, which improves horizontal scalability and supports operational controls (e.g., centralized invalidation, quota/ephemeral state handling).
  Trade-off: extra infrastructure and operational overhead.
• Why PostgreSQL as the primary datastore: Core entities (users, chats, prompts, admin data) are relational and consistency-sensitive. PostgreSQL provides strong integrity guarantees plus mature indexing/migration workflows.
• Why Next.js for frontend: Next.js supports route-based UI composition and production-ready optimization while allowing incremental migration from legacy static/script assets.

• Modular design: feature-specific blueprints keep routing and templates scoped and maintainable.
• Clear separation of concerns: integrations live in services/, keeping HTTP handlers thin and testable.
• Security-aware defaults: environment-based session configuration and secret management via .env.
• Composable UI assets: shared global assets with page-specific entrypoints for predictable styling.

• static/css/base/: reset, variables, common layout primitives
• static/css/components/: reusable UI components (e.g., sidebar, modal)
• static/css/pages//index.css: page entrypoints (import base + components)

Use BEM-style kebab-case class names and document purpose/dependencies at the top of each file.

• Set FASTAPI_ENV=production to enable secure cookie settings.
• Keep secrets out of version control; use .env or a secrets manager.
• Pin dependencies and update regularly.

Copyright (c) 2026 Kota Kawagoe

Licensed under the Apache License, Version 2.0 - see the LICENSE file for details.