Skip to content

REFERENCE_MAP.md

Latest commit

 

History

History
221 lines (174 loc) · 12 KB

REFERENCE_MAP.md

File metadata and controls

221 lines (174 loc) · 12 KB

Reference Documentation Map

Last Updated: January 2025

This guide helps you navigate flAPI's reference documentation and find the right document for your task.

Quick Navigation by Use Case

I'm getting started with flAPI

  1. First read: CONFIG_REFERENCE.md § 1 (Overview)
  2. Then: CLI_REFERENCE.md § 1 (Quick Start)
  3. Next: Follow the complete example in CONFIG_REFERENCE.md § Appendix A

I'm using the REST API

  1. Configuration: CONFIG_REFERENCE.md - All sections
  2. Runtime Management: CONFIG_SERVICE_API_REFERENCE.md § 2 (REST API Reference)
  3. CLI Client: CONFIG_SERVICE_API_REFERENCE.md § 3 (CLI Client)
  4. Authentication: CONFIG_REFERENCE.md § 7 (Authentication)

I'm using MCP (Model Context Protocol)

  1. Protocol Overview: MCP_REFERENCE.md § 1 (Overview)
  2. Getting Started: MCP_REFERENCE.md § 2 (Getting Started)
  3. Full Protocol Reference: MCP_REFERENCE.md § 3-7 (Methods, Tools, Resources, Prompts)
  4. Configuration: CONFIG_REFERENCE.md § 2.6 (MCP Configuration)
  5. Authentication: CONFIG_REFERENCE.md § 7 (Authentication)
  6. Error Codes: MCP_REFERENCE.md § Appendix B (Error Reference)

I'm integrating with MCP configuration tools

  1. Tool Overview: MCP_CONFIG_TOOLS_API.md (Complete reference)
  2. Integration Details: MCP_CONFIG_INTEGRATION.md (Architecture & Flows)
  3. Authentication: MCP_CONFIG_INTEGRATION.md § Authentication Flow
  4. Error Handling: MCP_CONFIG_INTEGRATION.md § Error Handling Strategy

I'm using cloud storage (S3, GCS, Azure)

  1. Overview & Examples: CLOUD_STORAGE_GUIDE.md
  2. Configuration: CONFIG_REFERENCE.md § 2.11 (Storage Configuration)
  3. Authentication: CLOUD_STORAGE_GUIDE.md § Authentication

I'm running the flAPI server

  1. Command-line Options: CLI_REFERENCE.md § 2 (Command-Line Options)
  2. Configuration: CONFIG_REFERENCE.md § 2 (Main Configuration)
  3. Environment Variables: CLI_REFERENCE.md § 3 (Environment Variables)

I'm configuring authentication

For REST/HTTP:

For MCP:

For Config Service API:

I'm troubleshooting errors

  1. MCP Errors: MCP_REFERENCE.md § Appendix B (Error Reference)
  2. Config Service Errors: MCP_CONFIG_TOOLS_API.md § Overview (Error Codes)
  3. HTTP Status Codes: CONFIG_SERVICE_API_REFERENCE.md § Appendix B (HTTP Status Codes)
  4. General Troubleshooting: CLAUDE.md § Troubleshooting

Document Relationship Diagram

                        ┌─────────────────────┐
                        │  CONFIG_REFERENCE   │
                        │  (Master Config)    │
                        └──────────┬──────────┘
                                   │
                    ┌──────────────┼──────────────┐
                    │              │              │
                    ▼              ▼              ▼
            ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
            │     MCP_     │ │   CONFIG_    │ │     CLI_     │
            │  REFERENCE   │ │   SERVICE_   │ │  REFERENCE   │
            │              │ │   API_REF    │ │              │
            └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
                   │                │                │
                   └────────┬───────┴────────┬───────┘
                            │                │
                    ┌───────▼────────┐ ┌────▼──────────┐
                    │  MCP_CONFIG_   │ │  CLOUD_       │
                    │  TOOLS_API     │ │  STORAGE_     │
                    │                │ │  GUIDE        │
                    └────────┬───────┘ └───────────────┘
                             │
                    ┌────────▼──────────┐
                    │  MCP_CONFIG_      │
                    │  INTEGRATION      │
                    │  (Advanced)       │
                    └───────────────────┘

Document Dependencies

  • CONFIG_REFERENCE: Foundation - all other docs reference configuration options
  • MCP_REFERENCE: Standalone MCP protocol documentation
  • CONFIG_SERVICE_API_REFERENCE: Depends on CONFIG_REFERENCE for configuration details
  • MCP_CONFIG_TOOLS_API: MCP tools for configuration management (references CONFIG_REFERENCE)
  • MCP_CONFIG_INTEGRATION: Advanced guide for integrating MCP config tools (references MCP_CONFIG_TOOLS_API)
  • CLI_REFERENCE: Server executable options (references CONFIG_REFERENCE)
  • CLOUD_STORAGE_GUIDE: Cloud storage usage (references CONFIG_REFERENCE)

Search by Topic

Authentication

Topic Primary Secondary
All auth schemes CONFIG_REFERENCE § 7 -
Basic Auth CONFIG_REFERENCE § 7.1 MCP_REFERENCE § 8.1
JWT/Bearer Auth CONFIG_REFERENCE § 7.2-7.3 MCP_REFERENCE § 8.2
OIDC Auth CONFIG_REFERENCE § 7.4 MCP_REFERENCE § 8.3
AWS Secrets CONFIG_REFERENCE § 7.5 -
Per-method auth MCP_REFERENCE § 8.4 -

Endpoints

Topic Document
REST endpoints CONFIG_REFERENCE § 3.1
MCP tools CONFIG_REFERENCE § 3.2, MCP_REFERENCE § 5
MCP resources CONFIG_REFERENCE § 3.3, MCP_REFERENCE § 6
MCP prompts CONFIG_REFERENCE § 3.4, MCP_REFERENCE § 7
Manage endpoints CONFIG_SERVICE_API_REFERENCE § 2.2

Caching

Topic Document
Cache configuration CONFIG_REFERENCE § 6
Cache management API CONFIG_SERVICE_API_REFERENCE § 2.4
Cache tools MCP_CONFIG_TOOLS_API § Cache Tools

Templates

Topic Document
SQL templates CONFIG_REFERENCE § 9
Template management API CONFIG_SERVICE_API_REFERENCE § 2.3
Template tools MCP_CONFIG_TOOLS_API § Template Tools

Error Codes

Protocol Document
MCP/JSON-RPC errors MCP_REFERENCE § Appendix B
Config tool errors MCP_CONFIG_TOOLS_API § Overview
HTTP status codes CONFIG_SERVICE_API_REFERENCE § Appendix B

Validators

Topic Document
All validators CONFIG_REFERENCE § 5
Integer validator CONFIG_REFERENCE § 5.1
String validator CONFIG_REFERENCE § 5.2
Enum validator CONFIG_REFERENCE § 5.3
Email validator CONFIG_REFERENCE § 5.4
UUID validator CONFIG_REFERENCE § 5.5
Date validator CONFIG_REFERENCE § 5.6
Time validator CONFIG_REFERENCE § 5.7

Storage & Cloud

Topic Document
Cloud storage guide CLOUD_STORAGE_GUIDE
VFS configuration CONFIG_REFERENCE § 2.11
S3 setup CLOUD_STORAGE_GUIDE § S3
GCS setup CLOUD_STORAGE_GUIDE § GCS
Azure setup CLOUD_STORAGE_GUIDE § Azure

CLI & Server

Topic Document
Server startup CLI_REFERENCE § 1
Command-line options CLI_REFERENCE § 2
flapii CLI client CONFIG_SERVICE_API_REFERENCE § 3

File Sizes and Scope

Document Size Scope Audience
CONFIG_REFERENCE 1700+ lines Complete configuration reference Developers, DevOps
MCP_REFERENCE 1700+ lines MCP protocol details AI integrators, Developers
CONFIG_SERVICE_API_REFERENCE 1550+ lines REST API & CLI API users, DevOps
MCP_CONFIG_TOOLS_API 720 lines 20 config tools AI integrators
MCP_CONFIG_INTEGRATION 500+ lines Integration guide Advanced users
CLI_REFERENCE 400+ lines Server executable DevOps, Deployment
CLOUD_STORAGE_GUIDE 200+ lines Cloud storage setup Cloud engineers

How to Contribute

When adding new features or configuration options:

  1. Document in CONFIG_REFERENCE.md - Add to appropriate section (§ 2 for main config, § 3 for endpoints, etc.)
  2. Link from secondary docs - If relevant to MCP/REST/CLI, add references in Related Documentation sections
  3. Update REFERENCE_MAP.md - Add new topic to search tables and quick navigation
  4. Verify cross-references - Use markdown link format: [Text](./FILE.md#section)

Related Documentation