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:

• See CONFIG_REFERENCE.md § 7 (Authentication) - primary source for all auth schemes

For MCP:

• See MCP_REFERENCE.md § 8 (Authentication)
• Details in CONFIG_REFERENCE.md § 7 (Authentication schemes and configuration)

For Config Service API:

• See CONFIG_SERVICE_API_REFERENCE.md § 1 (Authentication)
• Schemes in CONFIG_REFERENCE.md § 7

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

• CLAUDE.md - Project instructions and development guidelines
• Architecture Documentation - System design and components
• Design Decisions - Why certain choices were made
• Request Lifecycle - How requests flow through the system
• Component Docs - Detailed component documentation