Deployment and CI_CD

Deploying MOOC Utils covers:

• CI pipeline and automated checks
• Deploy paths for the FastAPI backend, Chrome/Firefox extension, and Next.js site
• Docker options
• Env-specific config
• Production concerns
• Monitoring, logging, and routine maintenance

The repository comprises three primary components:

• FastAPI backend service (notice-reminders)
• Chrome/Firefox browser extension (assignment-solver)
• Next.js marketing/landing website (website)

graph TB
subgraph "MOOC Utils Ecosystem"
NR["notice-reminders<br/>FastAPI Backend"]
EXT["assignment-solver<br/>Chrome/Firefox Extension"]
WEB["website<br/>Next.js Frontend"]
end
WEB --> NR
EXT --> NR

• FastAPI Backend: Provides REST APIs for course search, announcements, subscriptions, and user authentication. It supports CLI and API modes via command-line entry points.
• Assignment Solver Extension: A cross-browser extension supporting Chrome and Firefox with dynamic manifest generation, content scripts, background service workers, and UI panels.
• Website: Next.js frontend with Posthog analytics integration and API client for backend communication.

Key implementation references:

• Backend entry point and mode selection
• FastAPI app factory and router registration
• Settings configuration with environment variables
• Extension build scripts and manifest generation
• Next.js configuration and API client

The system follows a client-service architecture:

• The Next.js website communicates with the FastAPI backend via HTTP endpoints.
• The browser extension interacts with the same backend for user management, subscriptions, and notifications.
• The backend exposes modular routers for users, authentication, search, courses, announcements, subscriptions, and notifications.

graph TB
subgraph "Client Layer"
UI["Next.js Website"]
EXT["Browser Extension"]
end
subgraph "Backend Layer"
API["FastAPI Application"]
DB["SQLite Database"]
AUTH["JWT Auth"]
CACHE["In-Memory Cache"]
end
UI --> API
EXT --> API
API --> DB
API --> AUTH
API --> CACHE

FastAPI backend deployment#

The backend supports two operational modes:

• CLI mode for local tasks and maintenance
• API mode for production serving via Uvicorn

Operational flow:

• Entry point parses arguments to select mode
• API mode initializes Uvicorn with host, port, and reload options
• App factory creates FastAPI instance, registers CORS, and mounts routers
• Database initialization occurs based on settings and debug flag

sequenceDiagram
participant CLI as "CLI/Shell"
participant Entry as "notice-reminders/main.py"
participant API as "app/api/main.py"
participant UVICORN as "Uvicorn Server"
CLI->>Entry : "notice-reminders api [--host] [--port] [--reload]"
Entry->>API : "create_app()"
API->>API : "register_database(generate_schemas=debug)"
API-->>Entry : "FastAPI app instance"
Entry->>UVICORN : "run(app, host, port, reload)"
UVICORN-->>CLI : "Server ready"

Browser extension build and distribution#

The extension supports Chrome and Firefox with dynamic manifest generation and separate build targets:

• Build scripts for Chrome and Firefox
• Vite configuration with aliases and plugins for manifest generation and HTML transformation
• Manifest generation handles browser-specific permissions and UI elements

flowchart TD
Start(["Build Trigger"]) --> Mode{"Select Mode<br/>chrome/firefox"}
Mode --> |chrome| Chrome["Set browser=chrome<br/>Add sidePanel permission"]
Mode --> |firefox| Firefox["Set browser=firefox<br/>Add sidebarAction settings"]
Chrome --> Inputs["Resolve inputs:<br/>background/content/ui"]
Firefox --> Inputs
Inputs --> Plugins["Apply plugins:<br/>generate-manifest<br/>transform-html"]
Plugins --> Bundle["Rollup bundle<br/>with aliases and formats"]
Bundle --> Output["Write to dist/{browser}"]
Output --> End(["Extension Ready"])

Next.js website deployment#

The website integrates with the backend via an API client and includes Posthog analytics:

• API client reads NEXT_PUBLIC_API_URL from environment
• Rewrites route patterns for Posthog ingestion endpoints
• Uses React Query and shadcn/ui components

sequenceDiagram
participant User as "User Browser"
participant Next as "Next.js App"
participant API as "notice-reminders API"
participant Posthog as "Posthog EU Ingest"
User->>Next : "Navigate to pages"
Next->>API : "Fetch data via API client"
API-->>Next : "JSON response"
Next-->>User : "Render UI"
Next->>Posthog : "Analytics events"

Current repository includes a release workflow. The workflow orchestrates:

• Checkout repository
• Setup Bun for JavaScript tooling
• Install Python dependencies for the backend
• Run linting and tests for all components
• Build distribution artifacts for the extension
• Publish release assets

flowchart TD
A["Push/PR Event"] --> B["Checkout Code"]
B --> C["Setup Bun"]
C --> D["Install Python Dependencies"]
D --> E["Lint & Test Backend"]
D --> F["Lint & Test Website"]
D --> G["Build Extension Artifacts"]
E --> H["Publish Release"]
F --> H
G --> H

Containerization strategies for each component:

FastAPI backend container#

• Base image: python:3.12-slim
• Install system dependencies if needed
• Copy project files and install Python dependencies using the project configuration
• Set working directory and expose port
• Define health check endpoint
• Entrypoint uses the CLI entry point with API mode

graph TB
Base["Python 3.12 Slim"] --> Deps["Install Python Dependencies"]
Deps --> Workdir["Set Working Directory"]
Workdir --> Expose["Expose Port 8000"]
Expose --> Health["Health Check Endpoint"]
Health --> Entry["Entrypoint: CLI API Mode"]

Browser extension packaging#

• Build artifacts are generated under dist/{browser}
• Distribute prebuilt extensions for Chrome and Firefox
• Consider publishing to respective stores after signing

flowchart TD
Dev["Development Build"] --> Dist["dist/chrome & dist/firefox"]
Dist --> Store["Distribute to Stores"]

Next.js website container#

• Use Next.js official image or lightweight Node base
• Build static assets and serve with Next runtime
• Configure environment variables for API URL and analytics

graph TB
Node["Node.js Runtime"] --> Build["Next Build"]
Build --> Serve["Serve Static + SSR"]
Serve --> Env["Environment Variables"]

Backend settings are managed via environment variables:

• Database URL and debug mode
• CORS origins for web integration
• JWT secrets and token expiration
• Email SMTP settings for OTP delivery
• Platform URLs for NPTEL/Swayam scraping

classDiagram
class Settings {
+string app_name
+bool debug
+string database_url
+string swayam_base_url
+string nptel_base_url
+int cache_ttl_minutes
+string|None telegram_bot_token
+string|None smtp_host
+string|None smtp_port
+string|None smtp_user
+string|None smtp_password
+string|None smtp_from
+string[] cors_origins
+string jwt_secret
+int jwt_access_token_expire_minutes
+int jwt_refresh_token_expire_days
+int otp_expire_minutes
+string otp_delivery
+int otp_length
}

Recommended production practices:

Backend#

• Use a reverse proxy (Nginx/Caddy) to terminate TLS and forward to Uvicorn
• Scale horizontally behind a load balancer
• Persist SQLite in production using PostgreSQL with connection pooling
• Configure health checks and readiness probes
• Enable structured logging and metrics collection

Extension#

• Sign and publish to Chrome Web Store and Mozilla Add-ons
• Automate builds and releases via CI with version tagging
• Maintain compatibility matrices for Chrome/Firefox versions

Website#

• Deploy static build to CDN or static hosting
• Configure HTTPS and security headers
• Integrate analytics and error tracking
• Use environment-specific API URLs

• Backend logging: Configure structured logging with log levels and correlation IDs
• Metrics: Expose Prometheus-compatible metrics endpoint
• Tracing: Integrate OpenTelemetry for distributed tracing
• Frontend monitoring: Use Posthog for analytics and Sentry for error reporting
• Health checks: Implement readiness/liveness endpoints

• Database migrations: Use Tortoise ORM migrations and Aerich for schema changes
• Dependency updates: Regularly update Python packages and Node dependencies
• Security patches: Monitor advisories and apply updates promptly
• Backup strategy: Back up database and configuration files regularly

Common issues and resolutions:

• Backend fails to start: Verify environment variables and database connectivity
• CORS errors: Ensure frontend origin is included in CORS origins
• Extension not loading: Check manifest generation and browser permissions
• Website API failures: Confirm NEXT_PUBLIC_API_URL and network connectivity

Build artifacts with the existing scripts, inject secrets at deploy time, and watch API health plus extension store listings after a release.